servicenow-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v4.9.0
Disambiguation2/5
Multiple tools have overlapping purposes: execute_background_script and execute_script are essentially identical, and there are two parallel sets for update sets/changesets (list_update_sets vs list_changesets, etc.). The huge number of tools increases the chance of misselection despite detailed descriptions.
Naming Consistency3/5
Most tools follow a consistent verb_noun pattern (list_, get_, create_, update_, delete_), but there are notable deviations such as natural_language_search, execute_background_script vs execute_script, and multiple action verbs (run/trigger/execute) for similar operations. The _full suffix on list_va_topics_full breaks consistency.
Tool Count1/5
With 421 tools, the surface is far beyond what an agent can effectively navigate, even with a search_tools fallback. This size is overwhelming and contradicts the principle that each tool should earn its place; many tools are redundant or only marginally distinct.
Completeness4/5
The tool set covers an exceptionally wide range of ServiceNow domains (ITSM, HR, CSM, security, CMDB, DevOps, Flow, VA, PA, scripting, UI, mobile) and provides generic CRUD via query_records/create_record/update_record/delete_record. Minor gaps exist (e.g., no list_problems), but the generic tools cover these.
Average 3.7/5 across 400 of 421 tools scored. Lowest: 2/5.
See the Tool Scores section below for per-tool breakdowns.
- 5 of 5 community issues answered or closed in the last 6 months
- 73 commits in the last 12 weeks
- Last stable release on August 11, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Elastic License 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
View related servers

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
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 is a safe read operation. The description adds little beyond a vague domain scope; it does not disclose return format, filtering behavior, pagination, or what 'monitor' implies operationally.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is short, but it lacks substance and fails to convey actionable meaning. This is under-specification rather than effective conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain what the tool returns. It does not. It also fails to define 'active events' or 'critical infrastructure', and provides no information about default behavior or filter syntax, making it incomplete even for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (limit and query). The description adds no parameter-specific semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the vague verb 'monitor' instead of 'list' or 'retrieve', and it does not explicitly state that the tool returns a list of active events. It adds 'critical infrastructure' context, but the purpose remains unclear and relies on the tool name for interpretation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool or when to prefer alternatives. With many sibling list_* tools, there is no comparative context or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, but the description adds no behavioral context such as pagination, ordering, or response format. It provides no detail beyond the action itself, missing an opportunity to disclose useful behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise. However, it is under-specified, and the brevity results in missing critical information rather than efficient communication. It is not a model of well-structured minimalism.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with one undocumented parameter and no output schema, the description should at least clarify what 'mobile layout configurations' entails and what the 'limit' parameter does. It fails to provide sufficient context for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema includes a 'limit' parameter with no description (0% schema coverage). The description does not mention this parameter or explain its purpose, leaving the agent to guess about its semantics and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('mobile layout configurations'). It is specific enough to distinguish from sibling tools like list_mobile_applets or list_mobile_app_configs, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of scenarios, prerequisites, or exclusions, leaving the agent without decision-supporting context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) with idempotent behavior. However, the description adds no extra behavioral detail such as whether updates are partial or full replacement, any permissions needed, or side effects. The safety profile is covered by annotations, but behavioral context beyond that is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and to the point, but the '[Scripting]' tag is unclear and adds noise without meaningful value. It is not overly verbose, but it under-specifies rather than being appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description is severely incomplete. It does not explain return behavior, error handling, or whether the update is partial or full. Given the tool's simplicity, a few extra sentences about updatable fields and expected outcomes would make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only sys_id is described), and the tool description does not mention any parameters or fields. The description fails to compensate for low schema coverage, leaving the agent without any guidance on what 'label' or 'description' mean in the update context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('UI Builder component'), distinguishing it from sibling tools like create_uib_component and list_uib_components. It is specific enough to convey the core purpose, though it does not enumerate which fields or attributes can be updated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no context on when to use this tool versus alternatives, no prerequisites, and no notes on scenarios where it is appropriate. The '[Scripting]' tag is ambiguous and does not clarify usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotation contradiction: the description includes an explicit '[Write]' marker, while annotations declare readOnlyHint: true. This is a serious inconsistency that undermines trust. Additionally, no further behavioral details are disclosed (e.g., side effects, need for specific permissions, or what happens during test execution).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, but the '[Write]' marker is misleading and unnecessary, detracting from conciseness. It is not fully effective because the extra token creates confusion rather than adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of two parameters and a clear action, more context is still needed: no output format, no usage guidance, and no clarification of the contradiction. The description leaves the agent without enough information to invoke this tool correctly, especially regarding what a test run returns or its side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters (flow_sys_id, test_inputs) have clear descriptions. The tool description adds no extra meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear action ('Execute') and resource ('a flow') with a distinct mode ('test mode') and sample inputs. It is unambiguous about the tool's core function, though it does not explicitly differentiate from sibling tools like trigger_flow or run_atf_test.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The phrase 'in test mode' implies a testing use case, but there is no explicit when/when-not, prerequisites, or comparison to sibling tools such as trigger_flow or get_flow_execution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations indicate readOnlyHint=false (write operation), but the description says 'track', which is vague and could mislead. It doesn't disclose that the tool likely updates the asset's lifecycle stage, creates a history event, or may have side effects. It also doesn't mention permissions or reversibility. The description fails to add behavioral clarity beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no fluff, which is appropriately concise. However, it is so terse that it sacrifices clarity. It earns a 4 because it avoids unnecessary words and is front-loaded with the core action, though it could be more specific in the same length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., updated asset, confirmation, event record), what side effects occur (e.g., lifecycle event creation, audit trail), or any conditions like the asset needing to exist. The complexity is moderate (3 params, required fields), but the description leaves critical context missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all three parameters with descriptions, so the baseline is 3. The description's phrase 'stage transitions' loosely aligns with the new_stage parameter, but it adds no extra meaning about parameter formats, defaults, or relationships. Since schema coverage is 100%, the description does not need to compensate heavily.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Track asset lifecycle events and stage transitions' identifies the resource (asset lifecycle) and a verb, but 'track' is ambiguous—it could mean monitor or record, not necessarily mutate. The required 'new_stage' parameter implies an update, but the description doesn't explicitly state that it changes the asset's stage, nor does it clearly differentiate from similar tools like retire_asset or update_asset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. Sibling tools such as retire_asset, update_asset, and create_asset exist, but the description provides no exclusions, prerequisites, or scenarios. The agent must infer usage solely from the parameter names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only adds a redundant '[Write]' tag, which already matches the readOnlyHint=false annotation. No additional behavioral context such as required permissions, side effects, idempotency implications, or post-creation steps is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a single sentence with a clear verb and resource. However, the '[Write]' tag is redundant given the annotation, so the description isn't perfectly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with no output schema, the description is too minimal. It doesn't explain what happens after creation, any prerequisites, or the relationship to get/update/list VA topic tools. The schema covers field details, but the broader workflow context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all five parameters. The description adds no parameter-level detail, but the baseline of 3 is appropriate since the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and the resource (Virtual Agent conversation topic), making the purpose unambiguous. However, it does not explicitly distinguish from related sibling tools like update_va_topic or list_va_topics_full, so it stops short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The description does not mention that this is for new topics only, nor does it exclude cases better suited for updating or retrieving existing topics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the readOnlyHint=false annotation because grouped aggregate queries are inherently read-only. It also fails to disclose pagination behavior, side effects, or response format, making the behavioral profile misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but the phrase 'latest release:' is unnecessary and adds noise. Overall it is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should at least hint at result format or additional behavior such as grouping semantics or limits. It only provides the endpoint, leaving significant gaps for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for all 5 parameters with clear descriptions. The description adds the REST endpoint context but does not enrich understanding of parameter behavior 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs grouped aggregate queries (COUNT, SUM, AVG) on any table, which is specific. However, it omits MIN and MAX supported by the schema and does not distinguish from sibling analysis tools like trend_query or aggregate_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives or what prerequisites exist. It simply says 'on any table' without mentioning limitations, permissions, or cases where other query tools would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and idempotentHint=true, and the description adds only '[Write]' which duplicates the annotation. It does not disclose additional behavioral details like required permissions, validation behavior, or side effects beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary action, but it is overly sparse. While efficient, it omits valuable context that could be included without significant length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update operation with four parameters and no output schema, the description provides minimal context. It does not mention return values, error conditions, or the significance of the sys_id requirement, leaving the agent to infer critical usage details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only sys_id is described). The description does not compensate by explaining path, title, or layout semantics. It adds no meaningful parameter information beyond the bare field names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing UI Builder page', using a specific verb and resource. It distinguishes the tool from siblings like create_uib_page, delete_uib_page, and get_uib_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as update_uib_component or create_uib_page. The description only states what it does, with no contextual usage cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=false and destructiveHint=false, so the description need not repeat these. It adds the prerequisite that SCRIPTING_ENABLED=true, which is useful operational context. However, it does not disclose what happens when committing, whether the operation is reversible, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using only nine words. Every word contributes to the core message. However, the brevity leaves out essential context, but it is still efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain the commit behavior, prerequisites beyond the single mentioned one, and potential consequences. It only states the action and one prerequisite, leaving the agent with insufficient understanding of how the commit works and how it differs from similar tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter 'sys_id' with 100% coverage, including its description. The description adds no additional meaning to the parameter, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Commit' with the resource 'update set', clearly indicating the action. However, it does not distinguish from sibling tools like 'publish_changeset' or 'complete_update_set' which may perform similar operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The only additional information is a prerequisite (SCRIPTING_ENABLED=true), which is not guidance for choosing the tool. It lacks any mention of typical use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write operation. The description's '[Write]' tag merely duplicates that annotation without adding further behavioral context such as side effects, required permissions, or what happens to existing data. It adds no new information beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. The '[Write]' tag is arguably redundant, but the structure is efficient. It could have packed more useful information in the same space, so it doesn't earn a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with six parameters and no output schema, this description is woefully incomplete. It does not explain what the tool returns (e.g., the created KPI object or an ID), any special behavior, or how it fits with sibling tools like create_pa_indicator. Given the tool's complexity, the description provides insufficient context for an agent to invoke it correctly with confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so all six parameters (name, unit, field, table, aggregate, conditions) have descriptions. The description does not elaborate on parameter semantics, but the schema already carries that burden, making a baseline score of 3 appropriate. No additional insight is provided in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Create) and resource (Key Performance Indicator), with an additional scoping phrase 'from ServiceNow data' that adds context beyond the tool name. However, it does not distinguish itself from sibling tool 'create_pa_indicator', which likely overlaps in purpose, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, when to prefer create_kpi over create_pa_indicator, or any other contextual usage direction. The description leaves the agent to infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description's '[Write]' tag merely restates what is already implied by readOnlyHint=false and does not add meaningful behavioral context. No information is given about side effects, permission requirements, or handling of existing layouts, though annotations already cover the basic write 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence plus a tag, with no filler. It is minimally sized but not excessively verbose; however, it is arguably too terse to provide substantial value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a very sparse description, the agent lacks information about return values, error conditions, or how 'view' corresponds to parameters. The openWorldHint=true suggests unknown behaviors that are not explained, leaving the description incomplete for a create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions (100% coverage). The tool description adds no additional parameter semantics beyond what the schema provides, and the phrase 'specific view' does not clearly map to the 'table' or 'type' parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('create') and resource ('mobile layout') with context ('for a specific view'), clearly distinguishing it from list_mobile_layouts and other creation tools like create_mobile_applet. However, 'specific view' is ambiguous and not defined in the description, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as create_mobile_applet or list_mobile_layouts. There is no mention of prerequisites, intended scenarios, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds little beyond confirming the write, with no disclosure of potential errors, required permissions, or idempotency behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a single sentence plus a [Write] tag. It is front-loaded and contains no filler, earning a high score for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool, the description lacks crucial context such as return value (no output schema), error handling for duplicate routes, and required permissions. The available annotations provide some safety info, but the overall completeness is insufficient for an agent to use the tool without further assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters have schema descriptions (100% coverage), and the tool description does not add further semantic detail. The schema-level descriptions like 'Route path' and 'Target UIB page sys_id' are minimal but sufficient, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation (register) and the resource (a route/URL path in a UX app). It is specific enough to distinguish this from sibling tools like create_uib_page or create_ux_experience, though it doesn't explicitly call them out.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description simply states what it does, leaving the agent to infer usage context from the tool name and sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description adds nothing about search behavior, pagination, limit handling, or result format. It does not disclose how pattern matching works or what a response looks like, leaving the agent without crucial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no redundant or filler content. Every word contributes to the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with four parameters and no output schema, the description omits vital details: the meaning of limit, whether search is case-sensitive / wildcard, the response shape, and any scope-specific behavior. The openWorldHint is not explained, so completeness is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%; the description adds artifact-type examples (business rules, scripts, widgets) but doesn't clarify the undocumented 'limit' parameter or any matching semantics. This is the expected baseline for high schema coverage with minimal added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for platform artifacts by name, type, or scope, with concrete examples. It implies a cross-type search distinct from the specialized list_* and get_* sibling tools, though it doesn't explicitly name these alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus dedicated artifact-list tools (e.g., list_business_rules, get_business_rule). It lacks any when/not-to-use context or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds no further behavioral details such as return format, error behavior, or what 'details' includes. It contributes minimal value 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is appropriately sized for a simple get tool, though it is terse and lacks helpful elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should clarify what 'details' entails. It does not explain what fields or information will be returned, nor does it mention error cases or related list tools. For a simple get tool this is under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the sys_id parameter is described as 'PA job sys_id'. The description itself does not add extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get details') and clearly identifies the resource ('Performance Analytics collection job'). It distinguishes from siblings like get_pa_indicator and get_pa_dashboard by naming the PA collection job entity specifically. However, it does not explicitly state that it returns a single job by sys_id, which would fully disambiguate from list_pa_jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., using list_pa_jobs to find sys_id) or exclusions. The description offers only a bare statement of function with no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, but the description adds little beyond that. It fails to mention default limit, pagination, or that active defaults to true, which are behavioral details an agent might need.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. However, it is so brief that it borderlines on under-specification rather than efficient writing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool without an output schema, the description should clarify return format or default behavior. It does not, leaving the agent to infer important details about pagination, filtering semantics, or response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description's mention of 'optional search filter' aligns with the query parameter but does not add extra meaning beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'customer accounts', which matches the tool's name. It does not distinguish the tool from siblings like list_csm_contacts or list_csm_cases, so it lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_csm_account or list_csm_cases. The 'optional search filter' hint is not enough to establish clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral detail beyond the schema and annotations. It does not mention pagination, result size, or performance implications of openWorldHint. Although readOnlyHint covers safety, the description contributes little to transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that communicates the essential action with no redundant words or filler. It earns a perfect score for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the simple nature of the tool, the description lacks any mention of return value structure or relationship to the many sibling property-related tools. Since no output schema is provided, the description should have provided more context about the response and typical use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are fully documented in the schema (100% coverage), so the description's mention of 'optional filtering' adds no additional semantic meaning. Thus a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 ('system properties') with a clear scope ('with optional filtering'). It effectively conveys the core function, though it doesn't explicitly differentiate from the sibling 'search_system_properties' tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like search_system_properties or get_system_property. The description only states the action and optional filtering, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations correctly indicate readOnly and openWorld behavior, the description's phrase 'List all' conflicts with the schema's active filter defaulting to true, meaning only active topics are returned by default. This important behavioral nuance is not disclosed. The description also omits any note about pagination or limits, though the limit parameter exists in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb, resource, and key output details. There is no wordiness or redundancy; every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has four optional parameters and no output schema, the description is too sparse. It does not mention the active filter's default behavior, which directly undermines the word 'all'. It also offers no usage context or distinction from related tools, making the tool's behavior incomplete for an agent to reliably invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 context about the output containing 'category and status details' but does not enrich the meaning of the four parameters beyond what the schema already provides. It fails to clarify that 'active' defaults to true, which would have added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('List') and the resource ('Virtual Agent topics') and mentions the details included ('category and status'). However, the claim of listing 'all' topics is potentially misleading given the schema's default active=true, which would exclude inactive topics unless the parameter is overridden. This slight scope inaccuracy prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus sibling tools like list_va_categories or get_virtual_agent_topics. There are no explicit context hints, prerequisites, or alternative tool references, leaving the agent to infer the use case from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint and openWorldHint, so the description carries less burden, but it adds no behavioral context beyond the annotations. It does not describe what gets searched, result format, or any limitations, so minimal additional value is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded and contains no filler. It is appropriately sized for a simple search tool, though it is terse and could benefit from a bit more context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too thin for a tool with no output schema and many sibling search tools. It fails to explain what types of data can be searched, how results are returned, or how it differs from other search offerings, leaving the agent without enough context to use it reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes both parameters clearly (query and limit). The description adds no additional semantic meaning, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches ServiceNow using plain English, satisfying the verb+resource criteria. However, it does not distinguish itself from sibling search tools like nlq_query or ai_search, so it loses the differentiation point.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or preferred use cases, leaving the agent to guess based solely on the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent, non-destructive operation. The description only adds the redundant '[Write]' prefix and the verb 'Schedule', without disclosing what scheduling entails (e.g., whether invites are sent, whether the change record is updated, or what response is returned). This fails to add meaningful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no fluff. It is appropriately front-loaded with the verb. However, the inclusion of '[Write]' is slightly redundant given the annotations, but overall it is concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with no output schema and 4 parameters, the description is too thin. It does not explain what a successful scheduling does, how attendees are handled, whether the change_id is required to exist, or what happens on failure. The agent lacks essential context to invoke the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 4 parameters have individual descriptions. The tool description adds no extra parameter semantics, which is acceptable when the schema is self-sufficient. Baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Schedule' and the resource 'Change Advisory Board (CAB) meeting'. It is a specific verb+resource pair that distinguishes it from sibling tools like create_change_request or list_* tools. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives. It does not mention prerequisites, typical scenarios, or exclude cases. With many sibling tools for change management, the agent receives no decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the prefix '[Write]' which simply restates the readOnlyHint=false annotation, and 'future delivery' adds minimal behavioral context. It does not disclose side effects, required permissions, error behavior, or whether this replaces existing schedules. Given annotations already indicate a write operation, the description provides no additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that communicates the core purpose without waste. It is appropriately sized, though it omits potentially valuable detail. No redundancy or structural issues.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three parameters and no output schema, the description does not explain return values, error conditions, or scheduling semantics (e.g., cron vs ISO date behavior). The lack of usage guidance and behavioral detail makes this incomplete for a non-trivial write operation, especially given the large sibling tool context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with descriptions (100% coverage), so the schema is the primary source of parameter meaning. The description itself does not mention any parameter details or add further insight, matching the baseline score of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'schedule' with resource 'notification' and the scope 'for future delivery', making the primary purpose unambiguous. However, it does not explicitly distinguish this from sibling tools like create_notification or trigger_scheduled_job, which could be similar in function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as send_push_notification or schedule_cab_meeting. No context, prerequisites, or exclusions are provided, leaving the agent without decision support for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. However, it adds no additional behavioral context such as query syntax expectations, return format, or pagination behavior. The description provides no value 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb and resource. It is appropriately sized for a simple read-only search tool, though it could include a bit more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should clarify what the search returns (e.g., full CI records, summaries) and any default behavior. It also lacks usage context. Given the tool's simplicity, the description is minimal but leaves key questions unanswered for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (limit and query), so the schema fully documents their meaning. The description does not add further insight into how these parameters affect the search, but the baseline of 3 applies since the schema covers parameter semantics completely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'search' and the resource 'configuration items (CIs) in the CMDB', which conveys the tool's core function. It does not explicitly distinguish from siblings like get_cmdb_ci, but 'search' implies a list/filter operation while get_cmdb_ci likely fetches a single item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_cmdb_ci, list_relationships, or natural_language_search. The description gives no context for selecting this tool, so agents receive no decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a write operation with destructive potential, but the description adds no additional behavioral context. It does not disclose side effects, delivery guarantees, rate limits, or any consequences, and the [Write] marker merely restates the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence plus a [Write] marker. It is extremely concise with no wasted words, earning the highest score for structure even though other dimensions suffer from lack of detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's side effects (destructiveHint true) and the existence of sibling notification tools, the description is too sparse. It does not explain return values, target requirements (user vs group), or when to choose this over alternatives, leaving substantial gaps for a write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters have complete descriptions in the input schema (100% coverage), so the description does not need to explain them. It adds no extra meaning, which matches the baseline for fully-documented schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (send) and resource (push notification to mobile app users), giving a specific purpose. However, it does not distinguish this from sibling tools like create_notification or send_emergency_broadcast, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The description neither mentions conditions, prerequisites, nor contrasts with other notification-related tools. This leaves the agent without direction on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint: false), non-destructive (destructiveHint: false), and idempotent (idempotentHint: true). The description adds only a redundant '[Write]' tag and does not disclose any additional behavioral traits such as whether partial updates are supported, validation rules, or what happens on update failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a single sentence and a short tag. It is front-loaded and wastes no words. This is an example of efficient description structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested 'fields' object, no output schema, and no guidance on behavior or return value. The description is too sparse to provide a complete picture of how updates behave, leaving a significant gap in understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for both parameters ('Asset sys_id' and 'Fields to update'), giving 100% coverage. The description adds no extra meaning beyond that, so the baseline of 3 is appropriate; it does not compensate beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an IT asset record' clearly states the verb (update) and resource (IT asset record), making the tool's purpose explicit. It distinguishes from siblings like create_asset, retire_asset, list_assets, and get_asset by the specific action, though it lacks the added scope or detail seen in higher-scored examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of requiring an existing sys_id, how this differs from create_asset or retire_asset, or any context about the update workflow. The description offers no usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive operation, and the description merely states '[Write]', which adds little beyond the annotations. It does not disclose important behavioral details such as whether existing subflows are overwritten, permission requirements, or side effects on dependent flows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and front-loaded, but it is under-specified. It conveys the basic purpose but omits valuable context, making it insufficient rather than appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters (one required) and no output schema, the description is far too brief. It fails to clarify what a 'reusable subflow' is, how the 'inputs' array should be structured, or what happens after creation. The tool's overall complexity is not addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of the parameters with descriptions, so the baseline is 3. The description adds no additional parameter semantics beyond the schema, but it doesn't need to since the schema already documents each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and resource (reusable subflow), and the name 'create_subflow' is unambiguous. It distinguishes itself from sibling tools like list_subflows, get_subflow, and create_flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. There is no mention of prerequisites, scenarios where a subflow would be appropriate, or exclusions (e.g., 'use create_flow for process flows').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, yet the description says 'Update a record', implying a write operation. This is a direct contradiction. No mention of side effects, failure modes, or behavior when WRITE_ENABLED is false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action. The parenthetical prerequisite is efficiently integrated without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a complete schema, the description is minimal and conflicts with annotations, creating confusion about what the tool actually does. It does not describe return values, behavior when WRITE_ENABLED is false, or other side effects, leaving the tool under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'table' and 'instruction' are meaningfully described. The description adds no extra parameter meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Update a record using natural language' – a specific verb (update), resource (record), and method (natural language), distinguishing it from structured update tools like update_record. The prerequisite 'requires WRITE_ENABLED=true' adds operational context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No comparison to sibling tools such as update_record or natural_language_search. The description implies use for natural language instructions but does not explicitly state when to prefer this tool over alternatives or any exclusions. The WRITE_ENABLED requirement is a precondition, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the annotations: readOnlyHint=false while 'preview' implies a read-only operation. No additional behavioral context is provided, and this contradiction creates confusion about side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although schema coverage is high, the lack of an output schema and the misleading annotation leave the agent without a clear picture of the tool's return value or behavior. The short description does not compensate for these gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters (sys_id and limit) already described in the schema. The description adds no extra semantic value beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('preview') and resource ('Update Set'), clearly distinguishing it from sibling tools like list_update_sets and export_update_set. The scope ('all changes') adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any mention of prerequisites or the update set lifecycle. The agent is left to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), and the description's '[Write]' adds no extra behavioral detail. It does not mention fields like asset_tag uniqueness, required versus optional parameters, or what happens on creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that is easy to parse. However, the '[Write]' marker is redundant given the annotations, adding slight noise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters and no output schema, the description is too minimal. It fails to convey important context such as required fields, uniqueness constraints, or expected behavior beyond the schema information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of the parameters, so baseline is 3. The description itself adds no parameter-specific meaning, relying entirely on the schema for details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new IT asset record,' using a specific verb and resource. It distinguishes the tool from siblings like list_assets, get_asset, update_asset, and retire_asset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, no exclusions, and no prerequisites. The description simply states the action without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) and non-destructive behavior, but the description adds no additional behavioral context. The '[Scripting]' tag is vague and does not clarify side effects, permissions, or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently short, but the '[Scripting]' tag is unclear and slightly distracts from the core message. Despite this, it is a single sentence with no redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and lacks essential context: it does not explain what a macroponent is, what the tool returns, any prerequisites, or how it fits into the UI Builder workflow. With no output schema, agents have no information about the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so the schema covers most parameters. The tool description adds no extra meaning beyond what the schema provides, maintaining the baseline for adequately documented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('custom UI Builder component'), and clarifies the domain term 'macroponent'. This distinguishes it from sibling tools like create_uib_page, which targets pages rather than components.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as update_uib_component or list_uib_components. The description only defines the tool's purpose without providing context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description restates that this is a write operation ('[Write]') which is already implied by annotations (readOnlyHint=false), and adds no other behavioral context such as side effects, permissions, or what happens to existing configurations. It provides no value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that immediately conveys the tool's purpose with no wasted words. The '[Write]' tag is somewhat redundant but does not harm conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema covers parameters and annotations cover safety, making this minimally viable. However, the description lacks information about what a UX Experience configuration entails, how it relates to app shells, and any prerequisites or consequences. It leaves clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are fully described in the input schema, so the description does not need to elaborate. It adds no meaning beyond the existing schema parameter descriptions, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the specific resource ('a new UX Experience (app shell) configuration'), using 'app shell' to add specificity. It distinguishes from sibling tools that create other UX artifacts, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like create_ux_app_route or list_ux_apps. There are no prerequisites, exclusions, or contextual clues for selecting this over other creation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the name implies ('get' = read-only). Annotations already declare readOnlyHint=true and openWorldHint=true, but the description does not disclose return format, error behavior, or any side effects. It is not contradictory, but it contributes no additional transparency 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no waste. Every word earns its place, making it highly scannable for an AI agent. It is appropriately concise for a simple getter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple getter with one parameter and clear annotations, but there is no output schema and the description does not explain what a 'suite result' includes or how the result_sys_id is obtained. While the name and parameter description provide reasonable context, the lack of guidance on the result's structure or source keeps it at minimally adequate rather than complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter result_sys_id is fully documented in the input schema ('System ID of the suite result record'), providing a clear description. The tool description adds no extra parameter context. With schema coverage at 100%, the baseline of 3 is appropriate; the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get the results of a test suite run' uses a clear verb and identifies the resource (suite result). It is distinct from sibling tools like get_atf_suite (which gets the suite definition) and list_atf_test_results, though it does not explicitly name them as alternatives. The meaning is unambiguous enough for an agent to select it for retrieving suite run results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., having a previous suite run), how to obtain the result_sys_id, or exclude scenarios where another tool (like list_atf_test_results) would be more appropriate. This leaves usage context entirely to the agent's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the annotations already declare (readOnlyHint, openWorldHint). It does not mention pagination, ordering, default state filters, or any additional behavior, leaving the agent to infer from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no filler or redundant phrasing. It front-loads the action immediately, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and the tool is a simple list operation, the description is minimally adequate but lacks any notes about return value structure or filtering nuances. With strong annotations and schema coverage, the gap is only moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (limit, state, severity) have schema descriptions, so the baseline is met. The tool description adds no additional meaning or examples for the parameters, so it does not exceed the schema's coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'list' with the resource 'audit results and findings', clearly indicating the tool lists audit data. However, it does not provide any context that distinguishes it from other list tools in the sibling set, such as list_active_events or list_security_incidents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus other list tools, nor does it mention any prerequisites or alternative tools. It solely states the action without any contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 only the content scope ('committed update sets and app installs over time') but does not disclose behaviors like pagination, ordering, or result structure, which is acceptable for a simple read operation 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the primary action and resource. Every word adds value, no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (two optional parameters, no required fields, no output schema), the description provides a basic understanding of what the tool does, but it does not explain return format or the 'limit' parameter. It is minimally viable but lacks detail for full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% ('days' is described, 'limit' is not). The description does not mention parameters at all, leaving 'limit' completely unexplained. It provides no additional meaning beyond the schema, and with only half the schema documented, this is a clear gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('deployment history'), and clarifies scope with 'committed update sets and app installs over time'. This distinguishes it from siblings like list_deployments and list_update_sets, though it could be more explicit about the exact difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as list_deployments, get_deployment, or list_update_sets. The description simply states what it does without any contextual usage cues or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds 'recent' and the presence of status fields, but does not elaborate on ordering, pagination, or the full set of statuses (omits 'cancelled'). 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It efficiently conveys the verb, resource, and key detail about statuses, earning a high score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with complete schema and good annotations, the description is adequate but not fully complete. It lacks details on result ordering, output structure, and the full status set, but the schema and annotations cover the core needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3, but the description adds confusion by listing statuses as 'completed, error, running' while the schema says 'complete, error, cancelled' and notes it's a filter. This introduces inconsistency and adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as listing executions of a flow, with 'recent' adding a time dimension and statuses indicated. It distinguishes from 'get_flow_execution' through the plural 'executions' and 'list' vs 'get', though it does not explicitly mention that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_flow_execution or list_flows. The only implicit context is the required flow_sys_id parameter, but no explicit context or exclusion is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description does not contradict them. However, it adds little beyond what annotations provide, and it inaccurately references a 'policy' filter that does not appear in the schema, which could mislead the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. Every word contributes to the core purpose, making it easy to read and understand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 optional params, no output schema, low complexity), the description is minimally adequate but has gaps: it omits the 'state' and 'limit' parameters, doesn't clarify the policy filter absence, and provides no information about return structure or pagination. It is complete enough for a basic read-only list, but could be stronger.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters, so the baseline is 3. The description does not add meaningful semantics beyond the schema; it actually introduces confusion by mentioning a policy filter that is not a parameter. No extra syntax, format, or behavioral details are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('List') and resource ('GRC controls'), distinguishing it from sibling tools like list_grc_risks and list_compliance_policies. However, it mentions filtering 'by risk or policy' while the schema only includes risk_sysid, introducing slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives, nor does it mention exclusions or prerequisites. The optional filter mention is implicit but not actionable. There is no 'use this when...' context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint and openWorldHint, so the read-only nature is covered. However, the description adds no extra behavioral context, such as default active filtering (which is only in the schema), pagination behavior, or scope. There is no contradiction, but no incremental transparency 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler or redundancy. It is appropriately sized for a simple list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and leaves out return format, default behaviors, and relationship to sibling tools. With no output schema, the agent must guess what the response will contain. The readOnly and openWorld annotations help, but the description on its own is insufficient for confident tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention either parameter (limit or active). The schema covers active with a description, but the limit parameter is undocumented and the description does not compensate. With 50% schema coverage, the description should provide at least some parameter context, but it provides none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List' and the resource 'ServiceNow mobile app configurations', distinguishing it from the singular get_mobile_app_config and create_mobile_app_config. The plural 'configurations' aligns with the tool's name and purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_mobile_app_config or list_mobile_applets. The description does not mention any filtering, prerequisites, or exclusions, leaving the agent to infer context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the readOnlyHint annotation. It does not disclose pagination behavior, default limits, or how app_config filtering affects results, which would be useful for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no redundant words. It states the action and resource immediately, earning its place with the clarifying parenthetical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too minimal for a tool with no output schema and partial parameter descriptions. It does not mention response format, filtering behavior, or usage hints, making it incomplete despite the simple nature of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the parameters. The schema has 50% coverage (app_config described, limit not), and the description fails to compensate by clarifying the 'limit' parameter or how 'app_config' is used in filtering.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('mobile applets'), with a helpful parenthetical defining what applets are. This distinguishes it from sibling tools like list_mobile_layouts and list_mobile_app_configs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention any exclusions, prerequisites, or recommend related tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what annotations already provide. readOnlyHint and openWorldHint signal safety, but the description does not disclose search semantics, result ordering, or whether it searches full text or metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It concisely captures the tool's core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not state what the search returns (e.g., list of article summaries vs. full content). However, for a simple read-only tool with fully documented parameters and clear annotations, the information provided is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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's 'by keyword' aligns with the query parameter but adds no additional meaning for limit or knowledge_base.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches knowledge base articles by keyword, with a specific verb and resource. It is distinguishable from siblings like get_knowledge_article (which retrieves a single article) and list_knowledge_bases, though it does not explicitly reference them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like natural_language_search or ai_search. There are no exclusion criteria, prerequisites, or comparative context given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotation contradiction: annotations declare readOnlyHint=false and idempotentHint=false, while the description states 'Retrieve' which implies a read-only, idempotent operation. The description does not disclose any additional behavioral traits such as limits, authentication, or error semantics, and contradicts the provided annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, zero wasted words. The description is front-loaded with the action and object, making it immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lacks an output schema and the description does not mention return format, constraints, or error behavior. More importantly, the annotation contradiction undermines trust and the description is not sufficient to resolve it. For a simple tool, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter 'names' as an array of property names with 100% coverage. The description adds no extra parameter context beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('retrieve') and resource ('system property values'), and explicitly scopes to 'multiple' and 'single call', distinguishing it from single-property getters like get_system_property and listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching multiple property values at once but does not explicitly contrast it with alternatives or state when not to use it. It lacks explicit when/when-not guidance, though the intent is reasonably clear from the wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds little beyond the annotations. The '[Write]' tag merely echoes readOnlyHint=false. It does not disclose side effects, overwrite behavior, permission requirements, or failure semantics. Since annotations already cover the safety profile, the description should add context but does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action. No filler or redundant text beyond the '[Write]' tag, which is acceptable. It is appropriately sized for the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 5 parameters and no output schema, the description is minimal. It does not mention expected outcomes, error conditions, or how parameters like 'query' and 'columns' affect the list view. The schema covers parameter names, but the description leaves contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all five parameters are described in the input schema. The description itself does not add any parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Add or update') on a specific resource ('list view in an agent workspace'), which distinguishes it from sibling tools like create_workspace or get_workspace. The verb and resource are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or scenarios where another tool (e.g., create_workspace) would be appropriate. The description only states what it does, not when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the 'requires WRITE_ENABLED=true' requirement, which is not present in annotations. However, it does not disclose other behavioral traits such as return values, error conditions, or side effects. Annotations already cover readOnly and destructive hints, so the additional context is limited but nonzero.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. It states the core action and a key prerequisite efficiently, making every word valuable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse for a create operation. It does not mention what the response contains (e.g., sys_id of the created article) or any potential side effects. Since there is no output schema, the description carries the burden of explaining return behavior, which it fails to do. The schema covers parameters, but the overall context remains incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all 4 parameters (100% coverage), so the description does not need to add parameter details. It adds no additional meaning beyond what the schema provides, yielding the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new knowledge article') and the resource. It does not explicitly differentiate from sibling tools like update_knowledge_article or publish_knowledge_article, but the verb 'create' is unambiguous and distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The parenthetical 'requires WRITE_ENABLED=true' is a precondition, not a usage scenario, and there is no mention of using update for existing articles or publish for lifecycle transitions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare write/non-destructive behavior, and the description adds only "[Write]" and "recurring email delivery," which are largely inferable from the tool name and annotations. It does not disclose side effects such as non-idempotency implications, frequency validation, or whether an email is sent immediately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with a useful [Write] marker and no redundant wording. Every word contributes to the core purpose, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has 6 parameters and no output schema, yet the description provides only a high-level action. It lacks important context such as conditional parameter requirements (e.g., day_of_week for weekly frequency), expected return values, or behavior when required fields are missing. The description is too sparse for a scheduling operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema fully documents each parameter's name and description. The description adds no additional parameter semantics beyond the general purpose, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description "Schedule a report for recurring email delivery" clearly specifies the verb (schedule), the resource (report), and the delivery mode (recurring email), which differentiates it from generic scheduled job tools. It provides a specific and unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 siblings like schedule_notification, create_scheduled_job, or generate_report. It does not mention prerequisites, alternative tools, or exclusions, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false). The description adds the WRITE_ENABLED=true prerequisite, which is useful context. However, it does not disclose side effects, validation behavior, or return value expectations, so the added transparency is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no waste. It immediately communicates the core action and includes the key prerequisite.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 7 parameters and no output schema, the description is under-specified. It lacks context on what constitutes a security incident, required fields, or potential implications. The WRITE_ENABLED requirement is helpful but insufficient for a complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive text for all seven parameters. The description itself adds no parameter-specific semantics, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a Security Operations incident', specifying the action and resource. The qualifier 'Security Operations' differentiates it from generic incident creation, 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like create_incident or update_security_incident. The only additional information is the WRITE_ENABLED requirement, which is a prerequisite, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal a write operation (readOnlyHint false). The description adds no behavioral insights beyond restating the purpose; it does not disclose side effects on the included update sets, required permissions, or result of the operation. It provides almost no value over 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core purpose efficiently. The embedded '[Write]' tag is redundant given the annotations, adding minor noise, but overall structure is compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with no output schema, the description lacks essential context: what a solution package is, how 'selected update sets' are processed, what the response looks like, and any prerequisites or lifecycle implications. This leaves the agent under-informed for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema documentation covers 67% of parameters, leaving 'description' undocumented. The tool description does not mention any parameters or clarify their meaning beyond what the schema already states, so it fails to compensate for the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and the resource (solution package from selected update sets), and distinguishes this tool from siblings like create_update_set or export_update_set by specifying the packaging/distribution purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for distribution' implies a packing use case, but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The agent must infer the appropriate context from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, covering the safety profile. The description adds the term 'background' but does not explain behavioral implications such as asynchronous execution, result retrieval, or side effects. Some context is added, but significant gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with an active verb and no redundancy. The [Scripting] category marker is harmless and helps agents classify the tool. It is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, open-world script execution tool, this description is incomplete. It omits what 'background' means, how to obtain results, potential timeout or sandbox constraints, and any safety caveats. It also fails to differentiate from the sibling 'execute_script', leaving an agent without essential operational details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: 'script' is documented as 'JavaScript code to execute' and 'scope' as 'Application scope (default global)'. The description adds no further parameter-level meaning, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear action ('Execute') and resource ('background script'), with context that it is server-side JavaScript. However, it does not distinguish this from the closely named sibling 'execute_script', so the meaning of 'background' remains unclear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. There is no mention of when to use this tool versus alternatives like execute_script, no prerequisites, and no exclusions. The [Scripting] tag offers no practical direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the `readOnlyHint: true` annotation by requiring `WRITE_ENABLED=true` and running an initialization command that scaffolds a project. This is a serious inconsistency; the description should clearly indicate that this operation writes files and changes state, but instead the annotation suggests it's read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose. It includes the exact command and essential prerequisites without any filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lacks an output schema and the description does not explain what happens after initialization, what files are created, or how the parameters affect the result. The contradiction between readOnlyHint and the write operation leaves the agent without a clear behavioral model. A more complete description should address the write side effects and parameter usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides full coverage of all three parameters with descriptions (project name, template, target directory). The tool description does not add any additional meaning beyond the schema, so the baseline score of 3 for high coverage applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Initialize') and target ('ServiceNow fluent/now-sdk project'), and specifies the underlying command (`npx @servicenow/sdk init`). This distinguishes it from sibling tools like fluent_build and fluent_validate. No confusion about what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the preconditions (`FLUENT_ENABLED=true` and `WRITE_ENABLED=true`), giving clear context for when it can run. However, it does not provide explicit guidance on when to use this tool versus alternatives, such as when to use existing project setup commands.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) with side effects (openWorldHint=true). The description adds little beyond the redundant '[Write]' marker and the mechanism 'via import set.' It fails to disclose potential side effects, such as whether existing CIs are updated or how data is transformed, which is critical for an open-world write tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'Import CI data into CMDB via import set.' It is concise, contains no fluff, and the '[Write]' marker is a compact indicator. Every word contributes to its meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a simple schema, this is a write operation with open-world semantics. The description does not explain the import set process, expected record structure, or side effects, nor does it relate to sibling tools like create_import_set_row or run_transform_map. An agent lacks sufficient context to fully appreciate the tool's behavior and consequences.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover both parameters ('Array of records to import' and 'Target CMDB table (e.g. cmdb_ci_server)') at 100% coverage. The tool description adds no additional parameter semantics, so the baseline of 3 applies as the schema already handles the parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Import CI data into CMDB via import set.' It identifies the resource (CMDB) and the method (import set), which distinguishes it from sibling tools like search_cmdb_ci or create_ci_relationship. The wording is unambiguous and action-oriented.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, typical scenarios, or exclusions. While it states what it does, it lacks the contextual 'when to use' information needed for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, informing the agent this is a safe read operation that may return a partial view of data. The description adds no further context beyond the parameters, such as pagination behavior or what 'active' means, so it provides minimal added transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words. Every part is informative, and it follows the expected 'verb + resource + qualifier' structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description should clarify return format or point to related tools like get_sla_details for full details. It also omits what 'active' means, how filters are encoded, or any pagination details. This is a bare-minimum description that leaves the agent guessing about list behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with 'limit' and 'query' already documented in the schema. The description's phrase 'optional filters' adds no new meaning beyond what the schema says, so it does not compensate or enhance the structured parameter definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists active SLA records, using 'list' as a specific verb with a resource. It distinguishes from get_sla_details (singular retrieval) and list_csm_case_sla (CSM-specific) by implying it returns multiple SLA records filtered by active status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention get_sla_details for individual SLA details or any exclusions for other list tools. Context implies it is the default for active SLA lists, but that is not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds no additional behavioral context such as output format, reliance on a trained model, or data freshness. 'Using historical ML analysis' is a methodological note, not a behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. Every token contributes to communicating the core purpose, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is an ML prediction with no output schema, yet the description fails to explain what the response contains (e.g., risk score, category, confidence). It also does not clarify how the three optional parameters are used together or any prerequisites like a trained model. This under-specifies a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add any extra meaning beyond the schema, such as which parameters are primary or how they interact. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's action (predict), target (change request), and outcome (risk level), using a specific verb and resource. It distinguishes from ML siblings like ml_train_change_risk and ml_evaluate_model by emphasizing 'predict' rather than 'train' or 'evaluate'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives, nor any exclusions, prerequisites, or scenarios. It is not misleading, but offers no directional advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, establishing the tool as a safe read operation. The description adds that it returns 'structured ServiceNow data' via the NLQ API, but it does not disclose additional behavioral traits such as potential result format variability, response size limits, or that the NLQ may be interpreted in an open-world context. With annotations covering safety, the added value is moderate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that immediately states the tool's purpose without wasted words. It is front-loaded with the core action ('Ask a natural language question') and result ('get structured ServiceNow data'). It loses a point for not including any additional context that would aid in selecting or invoking the tool, but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 three well-documented parameters and no output schema, the description provides the essential function but omits details about the response structure or any limitations of the NLQ API. Given that the tool is straightforward and annotations cover safety, the minimal description is adequate but not comprehensive. It could benefit from a note about the type of data returned or how results are structured.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for all three parameters (question, limit, table), achieving 100% coverage. The description does not add any parameter-specific meaning beyond what the schema already contains. The phrase 'natural language question' aligns with the 'question' parameter but does not elaborate on syntax or edge cases, so it meets the baseline without surpassing it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Ask a natural language question and get structured ServiceNow data.' It specifies the NLQ API, which identifies the mechanism. However, it does not explicitly distinguish itself from sibling tools like natural_language_search, which may perform a similar function, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as natural_language_search or query_records. It only states what the tool does, leaving the agent without context for choosing among similar NLQ-based tools. No exclusions or alternative suggestions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate a non-read-only, non-idempotent write operation; the description adds only a redundant '[Write]' marker. It does not disclose side effects such as incident state changes, asynchronous execution, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that gets straight to the point. The '[Write]' tag is somewhat redundant but not distracting; overall it is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While annotations and schema cover safety and parameters, the description omits important contextual details like execution outcomes, potential impact on the incident, or when this tool should be preferred. For a security action tool, this leaves meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for all parameters (100% coverage), so the baseline is 3. The description adds no additional parameter meaning beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a security response playbook against an incident, using a specific verb and resource. It distinguishes itself from the generic execute_playbook sibling by focusing on security response and the incident target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like execute_playbook or list_security_playbooks. It lacks context about prerequisites, incident types, or expected scenarios for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide safety profile (not read-only, not destructive). The description adds the useful requirement WRITE_ENABLED=true, which is beyond annotations. However, it does not disclose how the update behaves (e.g., partial vs full update, field validation, return value).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence and front-loads the action. It earns its place by adding the WRITE_ENABLED requirement, though more behavioral detail could be added without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with complete schema and annotations, the description is minimally viable. It lacks information about the return value, success/failure behavior, or any constraints on fields, and does not clarify the distinction from generic update_record. Given the existence of sibling tools like update_epic and update_record, more contextual guidance would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for sys_id and fields. The description adds no additional parameter-level meaning, so it relies on the schema, which is acceptable but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the clear verb 'Update' with the specific resource 'agile story', distinguishing it from sibling tools like update_epic and update_scrum_task. It does not explicitly state the scope or excluded operations, but the object is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only mentions the prerequisite WRITE_ENABLED=true and does not provide any guidance on when to use this tool versus alternatives like create_story or update_record. No exclusions or when-not-to-use scenarios are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the multi-table scope but does not disclose return format, potential performance implications, or permission requirements. With annotations covering the main safety aspect, the description adds some value but not rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loading the main action and keeping unnecessary words to a minimum. The dash clause 'useful for capacity planning' is a brief, useful context. However, the phrase 'time periods' introduces ambiguity without explanation, slightly undermining structure clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should explain the return value(s), but it only states the action and a use case. The schema covers parameters well and annotations handle safety, but the missing return format is a significant gap for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both tables and query have clear descriptions in the schema. The tool description does not add any additional parameter-level detail beyond the schema; the mention of time periods is not explicitly tied to a parameter, so it adds no semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares record counts across multiple ServiceNow tables or time periods, with a specific verb and resource. It distinguishes from siblings like get_table_record_count, though the mention of time periods without a schema parameter creates slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'useful for capacity planning' provides a use case but no explicit guidance on when to use this tool versus alternatives such as get_table_record_count or query_records. There are no exclusions or alternative recommendations, so usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what annotations already provide. It repeats the write nature ('[Write]') which is already indicated by readOnlyHint: false, and fails to mention important traits such as the flow being created in draft state (since publish_flow exists) or any permissions needed. With annotations covering the safety profile, the description contributes no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence and is very concise, with no wasteful language. However, the '[Write]' tag is redundant given the annotation readOnlyHint: false, slightly reducing the efficiency of the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided and the description does not mention return values or post-creation state (e.g., whether the flow is active or draft). Given the sibling tool publish_flow, the description should clarify that create_flow likely creates an inactive flow, but it does not. This is a significant lack of context for a mutation tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 5 parameters, so the schema fully documents each parameter. The description adds no additional semantic meaning for the parameters (e.g., how they interact or required fields beyond 'name'), so it does not compensate or enrich beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and the resource (Flow Designer flow), with a specific verb+resource combination. It distinguishes itself from sibling tools like update_flow, list_flows, and get_flow by explicitly targeting the creation of a new flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the goal is to create a new flow, but provides no explicit guidance on when to use this vs. alternatives like create_subflow or create_flow_action. No exclusions or alternative recommendations are given, so the context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what annotations already indicate. The annotation readOnlyHint=false already signals a write operation, and the '[Write]' tag in the description merely reinforces that without adding details about side effects, uniqueness constraints, or what happens to existing configurations. It does not contradict annotations, but provides minimal extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence plus a short marker. It is front-loaded with the key information (action and object) and contains no filler, making it highly concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple create operation with 3 parameters and no output schema. The description is minimal but not misleading. However, it lacks any context about what a mobile app configuration entails, how it relates to sibling tools like list_mobile_app_configs, or any constraints on the fields. This is acceptable for a basic tool but leaves room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents 'name' and 'branding_color' with descriptions, covering 67% of parameters. The tool description does not add any parameter-specific information, so it relies on the schema. Since coverage is moderate and the description is silent, a baseline of 3 is appropriate—neither enhanced nor compensated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Create a new mobile app configuration.' This uses a specific verb ('Create') and a specific resource ('mobile app configuration'), distinguishing it from sibling tools like list_mobile_app_configs and get_mobile_app_config, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as create_mobile_applet or create_mobile_layout. There is no mention of prerequisites, required permissions, or scenarios where this tool is preferred, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating operation (readOnlyHint=false), so no contradiction. The description adds slight context (the broker feeds data to a page), but discloses no additional behavioral traits such as side effects, required permissions, or what exactly gets created. It meets the baseline but adds limited value 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the core purpose and includes a useful [Scripting] marker. Every word earns its place with no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has four parameters but no output schema, the description is minimal and does not explain the return behavior or prerequisites (e.g., whether the target page must already exist). It is adequate for a straightforward create operation but leaves some gaps for a fully self-sufficient description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all four parameters (name, page, query, table), so the schema already provides full parameter meaning. The description does not add any additional value beyond this, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('UI Builder data broker') with a specific purpose ('to feed data to a page'). It is clear and distinguishes from generic create tools, though it doesn't explicitly differentiate from sibling data broker or UI builder creation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Aside from the implied use case of feeding data to a page, there is no guidance on when to use this tool versus alternatives (e.g., creating a component or page first, or using list tools to inspect existing brokers). No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the description is consistent with a read-only operation. However, the description adds no extra behavioral context beyond that already available in the annotations, such as what the returned 'details' include, whether it requires specific permissions, or if it triggers any side effects. For a getter this is minor, but there is no additional transparency value added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler or redundant information. It is front-loaded with the verb 'Get' and immediately conveys the purpose. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 required param, no output schema) and the presence of annotations covering safety, the description is minimally adequate. However, it fails to specify what 'details' includes (e.g., test case definition vs execution results), which is ambiguous given sibling tools like get_atf_failure_insight and get_atf_suite_result. The description could be more complete by clarifying the exact return payload or the scope of 'details.'
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the sole parameter sys_id ('System ID of the test'), which is clear and sufficient. The description itself does not add any further meaning to the parameter, but because the schema already carries the heavy lifting, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get details of a specific test case' clearly states the action (get) and the resource (a specific test case), distinguishing it from sibling tools like list_atf_tests (which lists) and run_atf_test (which executes). The intent is unambiguous and specific enough for an agent to understand what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as list_atf_tests, get_atf_suite_result, or get_atf_failure_insight. There is no mention of prerequisites, exclusion criteria, or scenarios where another tool would be more appropriate. This leaves the agent without clear selection context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 minimal behavioral context beyond a generic 'optional filters' statement, which is already implied by the schema's optional parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the primary action and resource. Every word earns its place, and there is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with three optional parameters and strong annotations, but the description lacks context about the difference from get_my_approvals, pagination behavior, or return value expectations. Since there is no output schema, some additional explanation of the response format or usage context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters (limit, query, state), so the schema provides full parameter semantics. The description only says 'optional filters', adding no further meaning beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists approval requests with optional filters, providing a specific verb and resource. However, it does not specify the scope (e.g., all approvals vs. user-specific), which distinguishes it from sibling tools like get_my_approvals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as get_my_approvals, approve_request, or reject_request. The description does not mention any prerequisites or exclusions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds the requirement that SCRIPTING_ENABLED must equal true, which is useful behavioral context. However, it does not describe output format, pagination, or error behavior, which would enhance transparency further.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single succinct sentence that conveys the core purpose and a key requirement. There is no redundant information, and every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with schema-documented parameters, the description covers the essentials. However, the conflation of 'update sets' and 'changesets' alongside the sibling 'list_update_sets' creates ambiguity about scope, and the description does not clarify the relationship between these concepts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for its two parameters ('limit' and 'state'), so the schema already provides full parameter semantics. The description adds nothing beyond the schema, which aligns with the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action: 'List update sets (changesets)', with the verb 'List' and resource 'update sets'. However, it does not differentiate from the sibling tool 'list_update_sets', which likely serves a similar purpose, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('requires SCRIPTING_ENABLED=true'), but provides no guidance on when to use this tool versus alternatives like 'list_update_sets' or when not to use it. There is no mention of context or exclusions, leaving the agent without decision-making information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description only needs to add extra context. It adds the prerequisite SCRIPTING_ENABLED=true, which is useful. However, it doesn't describe the response format, pagination, or default sorting, beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb 'List', and includes a concise prerequisite in parentheses. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read-only list tool with complete schema documentation and helpful annotations. The description lacks explicit mention of filtering capabilities or return value structure, but the schema covers the parameters. The prerequisite adds useful context. Overall adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 4 parameters are fully documented in the schema with descriptions, so the description adds no additional parameter semantics. Baseline 3 holds because schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'List' and resource 'client scripts' clearly identify the action and target. It's distinguishable from sibling tools like get_client_script, create_client_script, and update_client_script, though it doesn't explicitly name any alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage condition is the prerequisite 'requires SCRIPTING_ENABLED=true'. No guidance is provided on when to use this tool vs alternatives, such as when to use get_client_script for a single script or create_client_script for a new one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what annotations already provide. The readOnlyHint and openWorldHint already cover safety and result completeness, but the description does not mention pagination, return format, or how filters combine, which are not disclosed elsewhere.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the purpose and lists key filters. Every word earns its place; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read-only list with fully described parameters and supportive annotations, but the description lacks any mention of return format or pagination behavior. Given no output schema, the agent must infer the response shape from the tool name, which is a moderate gap for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description merely names some filter parameters but adds no additional meaning beyond the schema, such as whether filters are ANDed or how the query parameter interacts with others.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('CSM cases'), along with the optional filters. This distinguishes it from singular get_csm_case and other list tools like list_csm_accounts/list_csm_contacts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_csm_case for a single case or close_csm_case for lifecycle actions. The mention of filters implies some use cases, but no explicit exclusions or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds minor context with 'recent' and 'tracked in ServiceNow,' but does not disclose behaviors like default ordering, pagination, or what fields are returned. This is adequate given the annotations but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence communicates the tool's core purpose without redundant details. It is well-front-loaded and every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the optional filtering parameters and annotations, the description is minimally sufficient but lacks important context: it does not clarify what 'recent' means, how results are ordered, or how this tool differs from 'list_deployment_history'. The absence of an output schema does not require return-value detail, but the gap in usage context prevents a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for limit, state, environment, and pipeline_sys_id. The tool description does not add any additional meaning beyond the schema, so the baseline of 3 applies since the schema carries the full parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('recent application deployments') and context ('tracked in ServiceNow'). It is clear about what the tool does, though it does not explicitly distinguish itself from the sibling tool 'list_deployment_history'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives such as 'list_deployment_history' or 'get_deployment'. There are no suggested use cases, exclusions, or context about how it differs from other deployment-related list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint: true, which already indicates a safe read operation. The description does not contradict this and adds no additional behavioral context such as pagination limits or return format, so the bar is met but not exceeded.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the operation, and contains no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the schema covers parameters, but there is no description of return values, pagination, or how it relates to sibling import set tools. Given the absence of an output schema, the description is minimally sufficient but lacks completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter clearly described. The description adds no extra semantic value and introduces a slight inconsistency by mentioning 'staging table' as a filter option without a corresponding top-level parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('List Import Sets') and mentions optional filters, making the purpose clear. However, it mentions filtering by 'staging table' which is not a direct parameter in the schema, causing minor ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_import_set or list_data_sources. The description simply states what it does without any when-to-use or when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint, but the description adds minimal behavioral context. It does not clarify whether playbooks and processes are returned together, how pagination works, or what the openWorldHint indicates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is appropriately sized for a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The annotations and schema cover safety and parameter semantics, but the description lacks information about return format and does not clarify the relationship to siblings like list_playbooks or get_process_automation. The ambiguity between 'playbooks' and 'processes' also remains unresolved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (limit, query, active) are fully described in the schema, so the description does not need to repeat them. With 100% schema coverage, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists Process Automation Designer playbooks and processes, using a specific verb ('List') and defining the resource scope. This distinguishes it from generic sibling tools like list_playbooks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_process_automation or list_playbooks, and does not mention exclusions, prerequisites, or contextual hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds little beyond the tool name; it does not disclose return format, whether relationships are direct/recursive, or behavior when no relationships exist. Annotations declare readOnlyHint and openWorldHint, but the description does not elaborate on what openWorldHint means in practice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear, front-loaded sentence with no fluff. Every word contributes to the meaning, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 parameter, the description is reasonably complete. However, the lack of an output schema and the openWorldHint annotation leave some ambiguity about result completeness and format, which the description does not address.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single parameter ci_sys_id with a clear description. The tool description does not add extra meaning beyond the schema, so a baseline score of 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Show' and the resource 'parent and child relationships for a CI', making the tool's purpose specific. However, it does not explicitly distinguish this from sibling tools like cmdb_impact_analysis, which might also show relationships.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when one needs to view CI relationship hierarchies, but provides no explicit guidance on when to choose this over alternatives like cmdb_impact_analysis. No exclusions or alternative tool references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds that results can be filtered by story, but doesn't disclose return format, pagination, or default behavior. It provides minimal additional 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the action. It contains no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and has good schema/annotation coverage, but the description omits mention of the other filters and doesn't explain return values or list behavior. Given the lack of an output schema, a bit more detail on expected results would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for all three parameters, including defaults and filter semantics. The description mentions only the story filter, which partially overlaps with schema. It doesn't add meaning for limit or assigned_to, so it doesn't enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 ('scrum tasks'), making the purpose clear. It also mentions an optional filter by story, which adds useful context. However, it doesn't mention the other filters (limit, assigned_to) or distinguish from sibling tools like list_stories, so it's not fully differentiating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like list_stories or list_my_tasks. There is no mention of prerequisites, exclusions, or typical scenarios. This is a clear gap in usage instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare `readOnlyHint: true` and `openWorldHint: true`, so the description does not need to cover safety. It adds domain context ('importing data into ServiceNow tables') but does not disclose behavior such as default limit, pagination, or ordering. Since annotations cover the read-only nature, a middle score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that delivers the core message without unnecessary words. It is front-loaded with the action 'List Transform Maps' and follows with relevant context. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation, the description is adequate but lacks context about its relationship to other transform map tools, such as `get_transform_map` or `list_transform_field_maps`. With no output schema and only sparse behavior details, a bit more information would help the agent decide when to use this tool, but it is not severely incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (`limit`, `query`, `target_table`) having clear descriptions in the schema. The tool description does not add any additional parameter semantics beyond what the schema already provides, so baseline 3 is applied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List Transform Maps' with a specific verb and resource, and adds context about importing data into ServiceNow tables. It distinguishes from sibling `get_transform_map` by the plural 'List' vs singular 'get', but does not explicitly call out the difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus related siblings like `get_transform_map`, `run_transform_map`, or `list_transform_field_maps`. The usage context is only implied by the tool name and description, with no explicit alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral traits beyond the annotations. It does not mention pagination, the default limit of 25, or that the 'state' parameter is optional (the schema indicates optionality, which the description might contradict by implying state is required). No contradiction with annotations, but significant gaps in disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the verb 'List' and the resource. It contains no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with good schema coverage and read-only annotations, the description is minimally adequate. However, it lacks usage differentiation from find_update_sets and omits behavioral details like default limit and optional state, making it incomplete for full contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three parameters (limit, query, state) with 100% coverage. The description adds no further meaning beyond what the schema already documents, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), the resource (update sets), and the filtering dimension (state). It distinguishes from sibling tools like create_update_set, switch_update_set, and complete_update_set by focusing on enumeration rather than mutation or lifecycle operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as find_update_sets or get_current_update_set. The description only states what it does, without addressing exclusions or alternative scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds 'optional search filter', which is a useful but minimal behavioral detail that is also present in the schema. It does not disclose pagination, default behavior without a filter, or output shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, front-loaded sentence that communicates the core function efficiently. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 with good annotations, the description is minimally adequate. However, it lacks explicit mention of the return format, pagination behavior, or what happens when no filter is provided, which are helpful but not critical details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so limit and query are fully documented there. The description only summarizes 'optional search filter' without adding additional meaning or examples beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'users', making the primary purpose obvious. It distinguishes from get_user (single user) and create_user/update_user (mutations), though it doesn't explicitly mention the scope (e.g., all users vs. filtered).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like get_user or search tools. No exclusions, prerequisites, or alternative references are provided, leaving the agent to infer usage from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'all' but the input schema's 'active' parameter defaults to true, meaning by default only active workspaces are returned, not all. This misstatement is not disclosed. The description also does not mention the limit parameter, pagination, or return structure. The readOnlyHint annotation covers safety, but the behavioral claim is misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb and resource. It contains no filler and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description omits critical context: the active filter default contradicts 'all', no explanation of limit, and no mention of what a 'configurable agent workspace' is or what the return format looks like. With no output schema, the description should provide more clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%; the 'active' parameter has a description but 'limit' only has a type. The description adds no clarification about 'limit' or how 'all' interacts with the active filter. It does not compensate for the undocumented parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all configurable agent workspaces' clearly identifies the verb (list) and resource (configurable agent workspaces), with a scope qualifier ('all'). This distinguishes it from siblings like get_workspace (single) and create_workspace (create).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as the broad listing tool for all configurable workspaces, but it does not explicitly state when to use this instead of get_workspace or create_workspace. No alternatives or exclusions are mentioned, making the guidance only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds only the '[Write]' tag, which merely duplicates the readOnlyHint=false annotation. It fails to disclose important behavioral traits such as whether training is asynchronous, how long it might take, or what side effects occur (e.g., model replacement). With annotations already covering the write status, the description contributes no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and resource, with a minimal '[Write]' tag. There is no wasted wording or redundant elaboration, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with a fully described schema and annotations, the description provides adequate purpose but lacks details about the return value or post-training behavior. Since there is no output schema, the agent does not know what result to expect, leaving a notable gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter solution_name with its default auto-detect behavior, giving 100% coverage. The description does not add any parameter-specific information, so it earns the baseline score of 3 without further enhancement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Trigger training') and the specific resource ('incident classification ML solution'), which distinguishes it from sibling ML training tools like ml_train_change_risk or ml_train_anomaly_detector. The verb and resource are precise, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, scenarios that warrant retraining, or differentiate from the many other ML training tools in the sibling list, leaving the agent without contextual selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the write nature is covered. The description adds the WRITE_ENABLED requirement, which is useful context, but it does not disclose what happens to the incident state (e.g., status becomes resolved) or any side effects. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and captures the key parameters and a critical requirement, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter write tool with full schema coverage and annotations, the description is mostly adequate. However, it lacks usage guidance and any explicit statement about the effect of resolution on the incident, which would be helpful 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.
Parameters3/5
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's mention of 'resolution code and notes' only restates the parameter names without adding format, syntax, or additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Resolve') and the resource ('an incident'), and mentions key parameters. However, it does not explicitly distinguish this from sibling tools like close_incident or update_incident, so it falls short of a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage-related information is the parenthetical 'requires WRITE_ENABLED=true', which is a prerequisite rather than guidance on when to use this tool vs alternatives. There is no mention of when to choose resolve_incident over close_incident or update_incident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint false, destructiveHint true), the description adds no behavioral context such as irreversibility, delivery guarantees, or impact. The '[Write]' prefix merely restates the mutation implied 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no wasted words, front-loading the core action. It is appropriately concise for the low complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema and annotations cover parameters and safety, the description omits important context like potential delivery behavior, whether recipients must be sys_ids, or what response to expect. For an emergency tool with destructiveHint, more context would be helpful, so it falls at a minimum viable level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all four parameters, so the description need not add parameter details. It mentions recipients generically but adds no additional semantics beyond 'users or groups'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Send') and identifies the resource ('emergency broadcast notification') and audience ('users or groups'), clearly distinguishing it from sibling notification tools like send_push_notification or schedule_notification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description lacks context about urgency, confirmation, or when a broadcast is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint: false) and idempotent (idempotentHint: true). The description adds 'Create or update' and '[Write]', but these do not provide additional behavioral context beyond what annotations convey. No extra details are given about overwriting behavior, type handling, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus a tagged indicator, front-loaded with the action and resource. It is concise with no wasteful words. The '[Write]' tag is slightly redundant given annotations but does not detract from clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple property setter, the description conveys the essential purpose, and the schema plus annotations cover parameters and safety. However, it lacks any note about return values, prerequisites like permissions, or differentiation from bulk/import tools. Given the low complexity, this is minimally adequate but not richly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with meaningful descriptions (name, type, value, description), so the baseline of 3 is appropriate. The tool description itself adds no parameter-specific meaning, but it is not required because schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Create or update a ServiceNow system property value.' It is unambiguous and distinguishes from sibling tools like get_system_property or delete_system_property by indicating it performs writes (create/update) on system properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like bulk_set_properties or import_properties. There is no mention of prerequisites, conditions, or exclusions. Only the basic action is stated, leaving the agent without decision support for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only behavior is covered. The description adds the categories of validation (best practices, security, performance) but does not disclose output format, whether any side effects occur beyond read-only, or how failures are reported. This is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or repetition. It efficiently conveys the action and its scope in 12 words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two required parameters and good annotations, the description is adequate but leaves gaps: no output schema means the agent does not know what kind of result to expect (e.g., pass/fail, list of issues). The mention of best practices/security/performance is useful but vague.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters with examples ('table' and 'sys_id'), achieving 100% coverage. The description adds no additional parameter-level meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates an artifact for best practices, security issues, and performance concerns, giving a specific verb and resource. However, it does not explicitly differentiate from sibling validation tools like validate_deployment or validate_query, relying on the schema to imply 'artifact' means things like sys_script or sys_script_include.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as validate_deployment, validate_query, or validate_property. The description only states what it does, leaving the agent to infer context from the name and parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds '[Write]' but that's redundant with readOnlyHint=false in annotations. It does not disclose any side effects, permissions, or what 'exit tasks' entail. Beyond the basic action, there is no 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, directly states action, no filler. The '[Write]' tag is a useful quick cue. Ideal length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description doesn't indicate what the response will be (e.g., created case sys_id). It also lacks context about employee validation, offboarding process steps, or prerequisites. Given the tool's complexity (4 params) and having a close sibling (create_onboarding_case), additional context would be necessary for an agent to confidently invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema describes all 4 parameters (reason, manager, last_day, employee_sys_id) with clear meanings. The tool-level description adds no additional semantics, so according to baseline (100% coverage) score is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses 'Create an employee offboarding case with exit tasks' – a specific verb (create), a clear resource (offboarding case), and a distinctive scope (exit tasks). This distinguishes it from sibling tools like create_onboarding_case, which deals with arrivals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance about when to use this tool over alternatives like create_onboarding_case or create_hr_case. The description only implies usage via the name and action; there are no exclusions, prerequisites, or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral detail beyond what the annotations already convey. The '[Write]' tag duplicates the readOnlyHint=false annotation, and 'Delete' is implied by the tool name. It does not mention irreversibility, permissions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence plus a write tag. No wasted words; the essential action and resource are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one well-documented parameter and annotations indicating destructiveness, the description is adequate. However, it lacks any mention of return behavior or prerequisites, preventing a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter sys_id is already fully described in the schema ('UIB page sys_id'). The description adds no additional semantic detail, so it relies on the 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Delete' with resource 'UI Builder page', clearly distinguishing it from sibling tools like get_uib_page, create_uib_page, and update_uib_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., retiring vs. deleting, or prerequisites). It simply states the action without context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description directly contradicts the annotations: it says WRITE_ENABLED=true and drives install/publish/testsuite actions, which are write operations, while annotations declare readOnlyHint=true. This is a serious safety inconsistency. Additionally, the description does not disclose side effects (e.g., publishing to app repo, installing app version, running tests) beyond the flags, so the agent cannot anticipate the mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose and immediately followed by the required flags. Every sentence adds value: the first states what it does and via what SDK, the second adds pipeline context and critical prerequisites. No filler or redundant repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite good schema coverage, the tool performs mutating actions (install/publish/testsuite) and has no output schema, yet the description does not explain what happens on success, whether operations are synchronous, or how results are returned. The readOnlyHint contradiction further undermines completeness, leaving a critical gap for a CI/CD tool that alters instance state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with clear descriptions for all 5 parameters, so the baseline is 3. The description adds no parameter-level detail beyond the schema, but it does mention the actions (install/publish/testsuite) that map to the action enum. No compensation is needed since schema fully documents each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs ServiceNow CI/CD operations via the SDK, specifically scoped-app install/publish and ATF test-suite runs. It uses specific verbs ('Run', 'Drive') and a distinct resource ('now-sdk cicd'), while also distinguishing itself from local build/install flows, which separates it from sibling tools like fluent_build and fluent_validate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: 'from a promotion pipeline, outside the local build/install flow' and lists required flags (FLUENT_ENABLED=true, WRITE_ENABLED=true). It implies when to use it but does not explicitly name alternative tools or state when not to use it, so it falls short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 'complete information', which implies a broad return set, but this is slightly contradicted by the optional 'fields' parameter that can limit results. It does not disclose response format, pagination, or permissions, but the annotation coverage lowers the bar.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single concise sentence with no filler. It communicates the core purpose immediately. The phrase 'complete information' is slightly vague but does not detract significantly from clarity, making it a well-structured minimal description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 good schema and read-only annotations, the description is minimally adequate. However, it does not clarify how 'fields' interacts with the 'complete information' claim, nor does it hint at when to prefer this over search_cmdb_ci. The absence of an output schema also leaves return behavior unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, as both parameters have descriptions: ci_sys_id as 'System ID of the CI' and fields as 'Optional comma-separated fields'. The tool description adds no extra semantic context beyond that, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get' and the resource 'configuration item', indicating a fetch operation for a single CI. It distinguishes itself from sibling tools like 'search_cmdb_ci' (search) and 'list_relationships' (relationships), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as search_cmdb_ci or other get_* tools. It lacks context on prerequisites, exclusions, or preferred scenarios, leaving the agent to infer usage from the tool name and parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is known. However, the description adds minimal behavioral context beyond the schema: it doesn't clarify what happens if both parameters are omitted, whether exactly one is needed, or what the returned results contain. The 'policy or control' scope is already present in parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant wording. It is efficient and easy to parse, though minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two optional parameters and no output schema, the description leaves ambiguity: it doesn't state whether one identifier is required, what happens when both are supplied, or what the response looks like. More detail would be expected for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 no additional meaning; the schema already explains policy_sys_id and control_sys_id, including that control is an alternative. No extra value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with a clear resource 'compliance assessment results' and scope ('policy or control'), distinguishing it from sibling tools like list_compliance_policies or get_license_compliance by focusing on per-policy/control assessment results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you have a policy_sys_id or control_sys_id) but does not explicitly state when to use this tool over alternatives, nor provide exclusions or prerequisites. The schema hints at alternative parameters, but the description lacks direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds 'complete details', implying that the response includes all fields unless the optional 'fields' parameter limits them. This is a small behavioral insight, but not rich context about return formats, error behavior, or pagination. With annotations present, this is a minimal but acceptable contribution.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It is front-loaded with the verb and resource, and every word earns its place. This is an example of efficient writing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with strong annotations and full schema coverage, the description is nearly complete. It conveys the core purpose and the role of sys_id. It lacks any mention of not-found behavior or relationship to sibling tools, but given the low complexity and absence of an output schema, it is sufficiently complete for an AI agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not explain each parameter beyond what the schema already provides. The phrase 'complete details' hints at the behavior of the optional 'fields' parameter (omitting it returns everything), which adds marginal value, but overall the description does little to enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: 'Retrieve complete details of a specific record by sys_id'. It names the resource (record), the action (retrieve), and the key identifier (sys_id), which makes the purpose clear. However, it does not explicitly distinguish itself from sibling tools like query_records or get_table_schema, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for retrieving a single record by ID as opposed to query_records for searching lists or get_table_schema for metadata. No exclusions or context are provided, so the agent receives no decision-making help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, which convey the safe read-only nature. The description adds no further behavioral context (e.g., return format, errors), but it does not contradict the annotations. This meets the minimum bar with annotations present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, and contains no fluff. It is concise and effectively structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-only tool with good annotations, the description adequately conveys the purpose and what it returns at a high level. However, since there is no output schema, the description could be more explicit about the structure of the returned schema (e.g., field names and types), so it does not fully reach a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the single 'table' parameter with a clear description ('Table name to inspect'), so the schema already documents the parameter fully. The tool description adds no additional parameter semantics, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Get') and the resource ('structure and field information for a ServiceNow table'). It is specific enough to distinguish from generic 'get_record' tools, though it does not explicitly differentiate from the sibling 'discover_table' tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'discover_table' or 'query_records'. The description only states what the tool does, without any context on use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds only the source table sys_cs_topic, but does not disclose additional behavioral details such as default filtering, pagination behavior, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. The parenthetical table name adds useful context without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 with fully documented optional parameters and safety annotations, the description is largely sufficient. However, it does not clarify how this tool relates to sibling list_va_topics_full, so it is not fully complete in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters (limit, active, category) with 100% coverage, and the description does not add parameter-level context beyond what is in the schema. This warrants the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb 'List' and clearly identifies the resource as 'Virtual Agent topics available in the instance' with the table sys_cs_topic. It is clear and unambiguous, but it does not explicitly distinguish itself from closely related sibling tools like list_va_topics_full or get_va_topic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as list_va_topics_full or get_va_topic. Usage is only implied by the verb 'List', with no mention of preferred contexts, exclusions, or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safe read-only nature. The description adds minimal context by specifying 'available' items but discloses no additional behavioral details like pagination or ordering, which is acceptable given the simple list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, succinct sentence that conveys the core function without any filler or redundancy. It is well-structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional parameters and no output schema, the description is sufficient. It conveys the list behavior and scope ('available'), while safety is covered by annotations. It does not explicitly mention filtering options, but they are present in the schema, making the overall tool definition complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for limit and category, so the schema carries full parameter meaning. The description adds no extra insight into parameter usage or relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists available service catalog items, using a specific verb and resource. It distinguishes from siblings like get_catalog_item (single item) and create/update/order, but does not explicitly reference alternatives like search_catalog.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_catalog_item or search_catalog. The description only states what it does, leaving usage context entirely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds no behavioral context beyond that—no mention of pagination, default limits, or return shape. It fails to leverage the opportunity to describe what the tool does with the query/limit parameters or how it behaves on empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, front-loaded with the action 'List' and the resource. It is appropriately brief for a straightforward list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 and optional parameters well-documented in the schema, the description is nearly sufficient. It misses a note about what the output contains (e.g., product codes, descriptions) and the effect of the limit parameter, but overall it is complete enough for a basic list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both limit and query having their own descriptions. The description adds no additional parameter meaning, but since the schema fully covers parameters, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action and resource: 'List products and services available in the CSM catalog.' It uses a specific verb and resource, but does not explicitly distinguish from sibling tools like list_catalog_items, so it misses full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a use case (when you want to see CSM catalog products/services) but provides no explicit guidance on when to prefer this over alternatives or any exclusions. It lacks contextual keywords like 'use for' or 'instead of'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint and openWorldHint, and the description adds no additional behavioral context such as pagination behavior, default filtering, or return format. It mostly restates the read-only nature of the tool without going beyond what annotations and schema already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that is front-loaded with the core purpose and includes useful examples. There is no wasted or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 is reasonably complete. It names the entity type and examples, and combined with the schema's parameter details, an agent can infer the tool's basic behavior. A minor gap is the lack of explicit mention of return fields, but this is acceptable given the straightforward nature of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has full (100%) description coverage for all three parameters, so the baseline is 3. The description's examples of HR services do not add meaningful detail about the parameters themselves, but the schema already provides sufficient semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'HR services', with concrete examples (Onboarding, Offboarding, Benefits, Payroll) that disambiguate it from sibling tools like list_hr_tasks or get_hr_service. It is specific and easy to interpret.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_hr_service or list_hr_tasks, and does not mention any exclusions or prerequisites. The intended use is only implied by the name and examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows it is a safe read operation. The description adds a little context by defining themes as 'color palettes, CSS variables,' but does not disclose other behavioral traits like pagination, sort order, or response structure. With annotations covering the safety profile, the description adds minimal but acceptable value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb and resource. The parenthetical about color palettes and CSS variables adds valuable context in a compact way, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward read-only list operation with one optional parameter and strong annotations, the description is adequately complete. It identifies the resource and its nature, and the schema covers the limit parameter. It does not explain return values, but the simplicity of the tool does not demand more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'limit' is already well-described in the input schema, including its default value (25). The description does not add any further meaning about the parameter or its usage. Schema description coverage is 100%, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Service Portal themes with a parenthetical defining what themes are (color palettes, CSS variables). The verb 'List' and resource are specific. It does not explicitly differentiate from the sibling get_portal_theme, but the list vs. get distinction is implicit in the name and description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as get_portal_theme or list_portal_pages. There are no exclusions, prerequisites, or context about which scenarios favor this tool. The usage is only implied by the verb 'List'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and openWorldHint annotations already convey that this is a safe, read-only operation, so the description doesn't need to repeat that. However, it adds little beyond stating 'List' and 'optional search', with no mention of pagination, default limit (though limit is in schema), or return shape. This is minimal additional context beyond an already informative annotation set.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the primary action and resource. It is appropriately sized with no wasted words, and every phrase serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward read-only list operation with two optional parameters and no output schema, so the minimal description is partly sufficient. However, it lacks context about what the returned list contains, how it relates to sibling tools like list_widget_instances, and the discrepancy between 'category' and 'description' is a gap. The annotations help, but the description doesn't fully cover the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description introduces an inconsistency by saying 'search by name or category' while the query parameter description says 'name or description.' This misalignment could confuse an agent selecting search terms. The description fails to add value beyond the schema and actively contradicts it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'Service Portal widgets', making its purpose unambiguous. It distinguishes itself from sibling tools like get_portal_widget, create_portal_widget, and update_portal_widget by focusing on listing. The optional search clause is a useful addition, even though it uses 'category' instead of the schema's 'description'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_portal_widget or list_portal_pages. It does not state any exclusions or mention prerequisites, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the description adds no additional behavioral disclosure beyond the resource name. It does not mention pagination behavior, return format, query encoding nuances, or any operational context beyond what the schema and name imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words or redundancy. It efficiently conveys the purpose and resource in minimal space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional, well-documented parameters and read-only annotations, the description plus schema is mostly sufficient. However, the lack of any return-value description or usage context means the agent gets little orientation beyond the tool name, so it is not maximally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive text for both parameters ('limit' and 'query'), so the schema carries the semantic burden. The description adds no parameter-level meaning beyond what is already present, matching the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the exact resource ('PPM projects (pm_project)'), distinguishing it from sibling operations like create_project, update_project, and list_process_automations. The parenthetical table name adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as create_project or update_project. The description does not mention filtering, pagination, or any exclusions, leaving the agent to infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds no additional behavioral context beyond the word 'available,' which aligns with the schema's active filter. It does not disclose pagination behavior or the fact that only active playbooks are returned by default.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, six-word sentence that is clear and free of filler. Every word contributes meaning without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description adequately states its function. However, since there is no output schema, it does not explain what the response will contain, and it does not differentiate from the similar list_playbooks tool. Still, the core task is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (limit, active, category) are described in the schema with 100% coverage. The description adds no extra parameter meaning, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clearly defined resource ('security response playbooks'), making the tool's purpose obvious. It distinguishes from run_security_playbook but not explicitly from sibling list_playbooks, though the 'security response' qualifier narrows the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an agent needs to retrieve security response playbooks, but lacks any guidance on when to prefer this over list_playbooks or run_security_playbook. No exclusions or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint=true, openWorldHint=true) already cover the safety profile. The description adds the scoping nuance that pages are listed within a specific app, but it does not disclose pagination behavior, return format, or permission requirements. Given the strong annotations, this is acceptable but not enriching.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with the action verb front-loaded. It contains no fluff and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with 100% schema coverage and read-only annotations, the description is mostly sufficient. However, the presence of the near-identical sibling 'list_uib_pages' creates ambiguity that the description does not resolve, and there is no output schema to clarify return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters (app_sys_id, limit, query) are fully documented in the input schema. The description adds no additional explanation, but this is acceptable since the schema carries the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), resource (pages), and context (Next Experience UI Builder application). It is specific enough to understand the tool's function, but it does not differentiate from the sibling tool 'list_uib_pages', which appears to serve a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like list_uib_pages, and no mention of prerequisites or exclusions. The description only states what the tool does, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds no additional behavioral context such as pagination behavior, default limit, or return format, which could be useful beyond what the schema offers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that communicates the core function without redundancy or excessive detail. It is appropriately sized for a list operation and front-loads the purpose effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no required parameters and a well-documented schema, and the read-only annotations cover safety. The description accurately identifies the resource and module. Some might expect explicit mention of default limit or alternatives, but the schema provides the filtering details, making the overall definition reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters are fully described in the schema (100% coverage), including allowed values for state and severity. The description itself does not elaborate on parameter semantics, but the schema carries the burden, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists vulnerability entries from the Vulnerability Response module, using the verb 'List' and specifying the resource. This distinguishes it from sibling tools like get_vulnerability and update_vulnerability, which target single records or modifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_vulnerability or scan_vulnerabilities. It does not mention appropriate scenarios, filtering strategies, or exclusions, leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's '[Write]' is redundant. The description does not add behavioral context such as whether training overwrites an existing model, how long it takes, or whether it is asynchronous. Given the annotation coverage, the bar is lower, but the description still adds no extra behavioral transparency beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with an explicit action and resource, plus a '[Write]' tag that reinforces the write nature. It is front-loaded and contains no unnecessary words. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a training operation with no output schema and no mention of return values, job IDs, or next steps. The description does not explain what the agent should expect after triggering training (e.g., asynchronous job creation, training history). Given the complexity of model training and the absence of an output schema, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully covers both parameters (table and field) with clear descriptions. The description's phrase 'specific table/field' merely echoes the schema without adding new semantics. Baseline 3 is appropriate since the schema does the heavy lifting and the description provides no additional parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Trigger training') and the resource ('anomaly detection model for a specific table/field'). It distinguishes this from sibling tools like ml_detect_anomalies (which infers) and ml_evaluate_model (which evaluates). The scope is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. The description implies usage for training an anomaly detector, but it does not mention exclusions (e.g., 'use ml_train_change_risk for risk models') or prerequisites. It is minimally implied by the tool name and context, but no explicit guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent, non-destructive operation, so the '[Write]' prefix is redundant. The description adds the scope ('network/infrastructure') but does not disclose potential side effects, asynchronous behavior, resource usage, or prerequisites beyond the schema. With annotations covering the safety profile, the minimal extra context warrants a middle score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. The '[Write]' prefix is brief and the verb+resource structure is immediately clear. Every word adds some value, and it is appropriately sized for a simple trigger operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not explain the outcome of the trigger (e.g., whether it returns a schedule execution ID), how to monitor the scan, or that it may be asynchronous. There is no output schema, so the agent lacks essential context about what happens after invocation. The description is too sparse for a tool with side effects and no output specification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have descriptions. The tool description adds no additional parameter semantics—it does not explain how to obtain schedule_id (e.g., via list_discovery_schedules) or what mid_server does beyond the schema. Baseline 3 applies because the schema fully describes the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Trigger') and identifies the resource ('ServiceNow Discovery scan') with a scope ('network/infrastructure'). This clearly distinguishes it from sibling tools like list_discovery_schedules (which lists schedules) and scan_vulnerabilities (which targets vulnerabilities). The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention that list_discovery_schedules should be used to find schedule_id, or that this is an action that triggers an asynchronous process. No when-not-to-use or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only operation (readOnlyHint=false). The description adds the 'internal' nature (not visible to end user) and the WRITE_ENABLED requirement. These provide some context beyond annotations, but the description does not explain what happens on failure or whether the note is appended or overwrites existing content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and a key prerequisite. No redundant filler or restatement of the tool name. It earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation with a fully described schema, the description is adequate but minimal. It omits what happens on success (e.g., return value) or failure, and whether the note is added to the activity log. Since no output schema exists, a bit more detail about effects would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents each parameter. The description adds no extra meaning beyond the schema, such as format of sys_id or examples for table. It only restates that it works on 'any ITSM record', which aligns with the table parameter's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add'), the specific resource ('internal work note'), and the scope ('any ITSM record'). The word 'internal' distinguishes it from sibling tool 'add_comment', which presumably adds a visible comment, so the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives like 'add_comment' or 'update_record'. It mentions a prerequisite ('requires WRITE_ENABLED=true'), but this is a constraint rather than usage direction. No exclusions or alternative tool references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the tool can execute POST, PATCH, and DELETE methods, but the annotations declare readOnlyHint=true. This is a direct contradiction: a read-only tool cannot perform write operations. The description and annotations are irreconcilable, severely undermining trust and safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and includes only essential details (method, URL, body, max operations). No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (batch operations with multiple HTTP methods), the description covers the basics but omits important behavioral details such as response format, ordering guarantees, partial failure behavior, and correlation via operation IDs (which the schema partially addresses). The annotation contradiction further exacerbates the overall incompleteness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with detailed descriptions for operations, id, method, url, and body. The description adds the 50-operation limit and mentions optional body, but these are already captured in the schema via maxItems and the body property. The description adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes multiple ServiceNow REST API operations in a single HTTP call, which is a specific verb+resource combination. It distinguishes itself from the many individual operation tools in the sibling list by focusing on batching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool by noting it reduces round-trips by 50-70% and has a maximum of 50 operations per batch. This gives clear context for batching multiple operations but does not explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is a write operation (readOnlyHint=false) and not destructive. The description adds no additional behavioral context, such as whether existing values are overwritten, how partial failures are handled, or permission requirements. The [Write] tag is redundant with the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that effectively communicates the tool's purpose without unnecessary words. It earns its place and is easily scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a batch write operation with no output schema, and the description does not mention return values, error behavior, atomicity, or permission requirements. For a one-parameter tool with good annotations, this is adequate but leaves gaps that could affect correct invocation and result interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the 'properties' parameter in detail ('Array of {name, value, description?} objects'), and schema coverage is 100%. The description adds no additional parameter meaning beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create or update'), the resource ('system properties'), and the batch scope ('multiple... in a single operation'), distinguishing it from single-property tools like set_system_property. The [Write] tag reinforces the mutation intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies batch usage with 'multiple' and 'single operation,' but provides no explicit guidance on when to prefer this tool over alternatives such as set_system_property for single updates or bulk_get_properties for reads. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds a minimal verb but no extra behavioral context such as whether the original is preserved, what fields are copied, or if scope is required. It does not contradict annotations, but also does not enrich them beyond the basic clone semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the tool's purpose. The [Scripting] tag adds minimal but potentially useful context. Every word earns its place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward clone operation with all parameters documented in the schema. There is no output schema, and the description does not explain return behavior or side effects. Given its simplicity and full schema coverage, the minimal description is acceptable but does not go beyond the bare essentials.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for each parameter (table, sys_id, new_name, target_scope). The description's 'new name/scope' phrasing maps to the new_name and target_scope parameters, but adds no extra detail beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Clone') and resource ('platform artifact') with explicit outcome ('to a new name/scope'). It clearly distinguishes itself from sibling artifact tools like push_artifact, pull_artifact, and sync_status by focusing on duplication rather than transfer or synchronization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or comparisons to similar artifact operations. The context is implicit from the verb 'clone,' but no explicit when-to-use or when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the mutation risk is known. The description adds the WRITE_ENABLED prerequisite, which is useful, but it does not disclose consequences such as the case being irreversibly moved to a closed state or any side effects. Given the annotation coverage, the description adds minimal context beyond the requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and object, followed by the key permission requirement. There is no wasted wording, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter tool, the description is adequate but missing context about the closing workflow—it doesn't explain that closing is typically a terminal action or what response the agent should expect. The lack of an output schema means the return value is unspecified, and the description does not clarify whether the tool returns the closed case or a simple success indicator. Still, the essential purpose and required permission are covered, earning a moderate score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already documented with a concise description. The description's phrase 'with resolution details' only reinforces the importance of resolution_notes but adds no new syntax, format, or value constraints beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Close') and resource ('CSM case') with the qualifier 'with resolution details', distinguishing it from sibling tools like create_csm_case, get_csm_case, and update_csm_case. It also names the permission prerequisite, although that's not purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus update_csm_case or close_incident. It does not state that closing is a final action or that it should be used after resolution is complete. There are no explicit exclusions or alternative tool mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the table-specific scoping to cmdb_rel_ci but doesn't disclose behavior like how orphan detection works (e.g., does it consider relationship direction or only direct relationships). Still, given the annotations, it provides baseline value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that communicates the tool's purpose without unnecessary words. It is appropriately concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read-only query with two optional parameters, and the schema and annotations cover the basics. However, the description lacks usage guidance, examples, or any mention of what the output looks like. It is minimally complete but leaves some ambiguity about the exact definition of 'orphan' in relation to relationship types.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters (limit and ci_class) with clear descriptions, achieving 100% coverage. The description does not add any additional parameter semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Find' and identifies the exact resource: CIs with no relationships in the cmdb_rel_ci table. This clearly distinguishes it from sibling tools like cmdb_find_duplicates and cmdb_find_stale, which target different criteria.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternative CMDB discovery tools such as cmdb_find_duplicates or cmdb_reconcile. The description only states what the tool does, not when it should be selected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only safety is covered. The description adds that it focuses on completeness metrics for server and network CIs, which is useful context. However, it does not disclose any additional behavioral traits such as return format, pagination, or required permissions, so it only partially extends beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb and resource. It contains no fluff or redundant information, earning the highest score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and read-only annotations, the description provides adequate context for a simple getter. It tells the agent what metric to expect (completeness) and for which CIs (server and network). It doesn't elaborate on the return format, but for such a simple tool, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there is no parameter semantics to explain. The baseline is 4 for 0-parameter tools. The description appropriately doesn't attempt to add parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves CMDB data quality metrics, specifically completeness of server and network CI data. This gives a specific verb+resource scope. However, it does not explicitly distinguish from sibling tools like analyze_data_quality or check_table_completeness, though the focus on server/network CI data provides some differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. There is no mention of exclusions or preferred scenarios. The description simply states what it does without context on choosing it over similar CMDB-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, but the description describes mutating actions (merge, retire, remove) and requires CMDB_WRITE_ENABLED, directly contradicting the annotation. This is a serious inconsistency, and the description does nothing to resolve or explain it. Without the contradiction, it would disclose some behavior, but the contradiction warrants the lowest score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loading the core purpose and actions. It includes a key prerequisite and a feature note (dry_run) without unnecessary detail. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, and the description does not explain return values, what happens after merge/retire/remove, or whether actions are reversible. While the core purpose and parameters are covered, the missing behavioral details and the annotation contradiction leave it incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents action, targets, and dry_run. The description adds minimal extra value, only reiterating dry_run mode and the write requirement. This aligns with the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool acts on duplicate, stale, or orphan CIs with specific actions (merge, retire, remove). It distinguishes itself from sibling tools like cmdb_find_duplicates, cmdb_find_orphans, and cmdb_find_stale, which likely only identify issues, while this tool acts on them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for reconciliation actions on CIs, and it states a prerequisite (requires CMDB_WRITE_ENABLED). It also mentions dry_run mode for safe previewing. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive, non-idempotent operation. The description adds only the purpose but does not disclose side effects such as locking the update set or irreversibility. It fails to provide meaningful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus a [Scripting] tag, conveying the essential action with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter state-change tool, the description is largely sufficient. However, it lacks context about the consequences of marking complete (e.g., whether the update set becomes locked) and how it relates to the many sibling update-set tools, leaving some ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes sys_id as 'Update Set sys_id' with 100% coverage. The description adds no additional parameter information, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Mark' with a clear object 'Update Set' and explains the intent 'ready for migration', distinguishing it from sibling tools like export_update_set or switch_update_set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'ready for migration' implies the tool is used to prepare an update set for migration, but it does not explicitly state when to use it versus alternatives, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) and non-destructive nature (destructiveHint=false). The description's '[Write]' prefix is redundant but consistent. However, it provides no additional behavioral context such as behavior on duplicate variable names, whether the variable is appended or replaces, or failure modes. The openWorldHint suggests possible side effects not disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with a '[Write]' prefix that immediately signals the operation type. It is concise, with no wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not explain what is returned (e.g., the sys_id of the created variable) or any error conditions. It also does not mention the dependency on an existing catalog item beyond the parameter itself. While the schema covers parameter details, the lack of return behavior and side-effect disclosure leaves the description adequate but incomplete for a write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema descriptions cover all six parameters with 100% coverage, including the allowed values for 'type'. The tool description adds no extra parameter semantics beyond what the schema already provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Add') and clearly identifies the resource ('form variable' to a 'service catalog item'). This distinguishes it from sibling tools like create_catalog_item, which creates the item itself, and order_catalog_item, which is a different action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool vs alternatives, nor any prerequisites such as the catalog item already existing. The description merely states what it does, leaving the agent to infer that it should be used as a sub-action for an existing catalog item.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description's '[Write]' prefix aligns with readOnlyHint=false but adds no behavioral details beyond what annotations already convey—such as failure modes, uniqueness constraints, or side effects. It neither enriches nor contradicts the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Compact and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While simple, the description omits details like whether existing relationships are checked, required permissions, or the return value. For a 3-parameter create tool with no output schema, it is minimally adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters (type, child, parent) with descriptions, so the description adds no additional parameter semantics. Baseline 3 applies due to 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' and identifies the resource as 'a relationship between two CMDB Configuration Items,' clearly distinguishing it from read-only sibling tools like list_relationships and get_cmdb_ci.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as checking existing relationships with list_relationships first. Usage is only implied by the verb 'Create.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the WRITE_ENABLED=true requirement, which is useful context, but does not disclose side effects, return behavior, or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler; it states the operation and the key precondition clearly and efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema and annotations cover parameters and safety, but the description lacks any mention of the return value or success behavior. With 9 parameters and no output schema, some additional context would help, but it is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 9 parameters have schema descriptions (100% coverage), and the tool description adds no additional parameter-level meaning, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' and resource 'Customer Service case', which clearly distinguishes it from sibling tools like update_csm_case, close_csm_case, and other create_* tools for different domains. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only mentions a precondition (WRITE_ENABLED=true) but does not explain when to choose this over alternatives like create_incident or create_hr_case, nor does it provide exclusions or alternatives. There is no guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds the WRITE_ENABLED=true requirement, which is useful context not captured by annotations. However, it does not disclose other behavioral traits like return value or side effects, so credit is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and contains no filler. It is appropriately concise for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with full schema coverage and annotations. However, it lacks usage guidance and does not explain the return value (no output schema exists). Still, for a straightforward create operation, the provided information is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already documented. The tool description adds no parameter semantics beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new epic' uses a specific verb and resource, clearly distinguishing it from siblings like update_epic and list_epics. The purpose is unambiguous and immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as update_epic or create_story. The only extra information is the WRITE_ENABLED=true prerequisite, which is not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the write nature is known. The description adds a '[Scripting]' tag, which gives a hint about the target audience, but does not disclose additional behavioral traits such as permissions, validation, or side effects. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence plus a tag. It is front-loaded and wastes no words, fitting the standard for efficient descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema covers parameters and annotations provide safety hints, the description lacks information about return values, prerequisites, or any special context needed for scripting. For a creation tool with multiple parameters, this is adequate but leaves some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not add any meaning beyond the input schema, which already documents all five parameters with descriptions. Since schema description coverage is 100%, the baseline of 3 is appropriate; no extra value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a custom Flow Designer action, using a specific verb and resource. It distinguishes from the sibling create_flow and other create tools by explicitly naming the artifact type (action).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not explain when to use this tool versus alternatives like create_flow or create_subflow, nor any prerequisites or context for creating an action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The '[Write]' label is redundant with the annotations (readOnlyHint=false), and the description adds no additional behavioral context such as side effects, permissions, or irreversibility. However, it does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence plus the [Write] tag, containing no fluff or redundancy. It is concise and front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with strong schema coverage and no output schema, the description is minimally viable. However, it does not clarify relationship to mobile app configs or any behavioral nuances, making it adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are documented in the input schema. The description adds no extra parameter meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (create) and the resource (mobile applet) within a mobile app, distinguishing it from sibling tools like create_mobile_app_config and create_mobile_layout. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, prerequisites, or context. The description simply states the action without any usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a write operation. The description adds the prerequisite flags (NOW_ASSIST_ENABLED + WRITE_ENABLED) which are useful behavioral context. However, it does not describe what the tool returns, whether validation occurs on the steps, or what side effects happen on creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the primary purpose and includes the critical precondition. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with a nested steps parameter, the description conveys the core function and prerequisites. However, it does not mention the response/return value (e.g., whether the created playbook ID is returned), which is pertinent for subsequent actions like 'execute_playbook'. Given the absence of an output schema, this gap affects completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for all parameters (name, description, steps) with descriptions, so the baseline is 3. The description adds only general context about 'ordered steps that chain tool calls' but does not explain step syntax, condition expressions, or error handling semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'playbook definition', and specifies that it contains 'ordered steps that chain tool calls'. This distinguishes it from the sibling 'execute_playbook' (which runs a playbook) and 'list_playbooks' (which lists them), though it does not explicitly mention these alternatives or contrast with 'create_flow'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating it creates a playbook definition for chaining tool calls, and names required prerequisites (NOW_ASSIST_ENABLED + WRITE_ENABLED). It does not explicitly say when to use this tool over alternatives like 'create_flow', nor does it state when not to use it (e.g., for one-off scripting).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false), so no contradiction exists. The description adds useful context about the required WRITE_ENABLED setting and that the report is saved, but it does not disclose what the tool returns or whether duplicate titles cause errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the key action and prerequisite front-loaded. Every word adds value, and there is no unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the input schema is rich and fully describes parameters. The description does not mention return values or validation behavior, and given the moderate complexity (8 params, 3 required), this is a slight gap. It is minimally viable but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already documents all 8 parameters. The description adds little parameter meaning beyond the phrase "any table," which maps to the 'table' parameter, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Create a new saved report on any table." It distinguishes this from sibling tools like update_report, list_reports, and generate_report by emphasizing "saved" and "any table," making the creation scope clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly say when to use this tool versus alternatives such as generate_report for ad-hoc reports or run_aggregate_query for data exploration. The only guidance is the prerequisite "requires WRITE_ENABLED=true," which is a condition, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds the SCRIPTING_ENABLED requirement, which is useful context beyond the annotations. It does not disclose other behavioral details like what happens on creation or return values, but the bar is lower due to annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the essence and a key requirement. No wasted words, and it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema and annotations provide substantial detail, but the description does not help differentiate this tool from many sibling create_* tools, nor does it explain what a script include is or when it is appropriate. Given the tool's relative simplicity and the rich schema, a score of 3 reflects that it is minimally viable but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 7 parameters are already documented. The description adds no parameter-specific information beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'script include', making the tool's purpose unambiguous. It distinguishes from sibling tools like get_script_include and update_script_include through the verb, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the name and description, and the note 'requires SCRIPTING_ENABLED=true' provides a prerequisite. However, it does not explicitly state when to use this tool versus other creation tools like create_business_rule or create_flow, and no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey destructiveness (destructiveHint=true). The description adds the WRITE_ENABLED requirement, which is useful operational context beyond annotations. However, it does not describe other behavioral aspects such as irreversibility or cascading effects, but with annotations covering the core safety profile, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It clearly communicates the operation and a key precondition, though it is slightly thin on usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete tool with annotations marking it destructive, the description is reasonably complete. It covers the operation, the target object, and a permission requirement. No output schema exists, but none is needed for a simple delete confirmation. The description could mention ripple effects, but annotations and simplicity mitigate the need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single parameter attachment_sys_id, and the description does not add additional meaning beyond what the schema provides. Baseline of 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the target resource ('an attachment from a record'), which is specific and distinguishes it from siblings like upload_attachment, list_attachments, and get_attachment_metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given for when to use this tool versus alternatives. The only additional context is 'requires WRITE_ENABLED=true', which is a prerequisite rather than usage direction. It does not mention when deletion is appropriate or suggest any alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates a safe read operation. The description adds little beyond naming the resource type; it does not disclose what 'details' includes, error behavior, or any special constraints. With annotations covering safety, the description's marginal behavioral context is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is optimally concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one well-documented parameter and read-only annotation. However, there is no output schema, and the description does not specify what 'details' are returned or any prerequisite (e.g., event must already be registered). This leaves some ambiguity but is adequate for a basic getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter, which provides a clear example ('incident.created') and mentions sys_id as an alternative. The tool description itself adds no extra parameter meaning, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get'), the resource ('details of a specific registered event definition'), and distinguishes it from sibling tools like list_event_registry by emphasizing 'specific' and 'details'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use this tool when you need details of one event definition rather than listing all. No explicit alternatives or exclusionary guidance are provided, so it falls at the minimum viable level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this as a write operation (readOnlyHint: false) and the description adds the meaningful 'create or update' (upsert) behavior. However, no additional context is provided about side effects, permissions, rate limits, or other behavioral traits beyond what annotations and schema already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently communicates the action and resource. Every word contributes; the [Write] marker is redundant but harmless.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with no output schema, the description does not explain expected return values or error behavior. It does mention create/update, but lacks context about batch semantics, the effect of dry_run, or potential failure modes, making it adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full coverage (100%) with verbose descriptions for both parameters, including dry_run's purpose and an example for properties. The description adds no extra parameter semantics beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Import' with the resource 'system properties' and mechanism 'from a JSON object', clearly distinguishing it from retrieval, deletion, or single-property tools. The explicit mention of 'create or update' specifies the upsert nature of the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus similar siblings like bulk_set_properties or set_system_property. The name 'import' implies batch import, but the description does not state exclusions or alternatives, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only and open-world, so the safety profile is covered. The description adds the asset domain and filtering options but does not disclose additional behaviors like pagination, response format, or default limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that communicates the primary action and key filters without any unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple list tool with 6 optional parameters and no output schema, but it leaves out practical details like default limit or return shape. It relies heavily on the schema, which is complete but the description itself is bare.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter descriptions carry full weight. The tool description mentions three filters (state, class, assigned user) but adds no extra meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists IT assets with optional filters, which is specific and distinct from sibling tools like get_asset (retrieve single asset) and list_software_licenses (licenses specifically).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any exclusions. The sentence simply states what it does without contextual cues for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true, establishing it as a safe read operation. The description adds the useful prerequisite that SCRIPTING_ENABLED must be true, which is behavioral context beyond annotations. However, it does not disclose filtering behavior, pagination, or return format. Given annotation coverage, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core action and includes a critical prerequisite. It is concise and contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with optional parameters and no output schema. The description covers the basic action and a prerequisite, but lacks usage guidance regarding alternatives or any mention of what the response contains. For a minimal list tool, it is minimally complete but leaves gaps in when-to-use context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents all three parameters (limit, table, active) with clear descriptions, giving 100% schema description coverage. The description adds no additional parameter semantics beyond the schema. Baseline 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List business rules', with a specific verb and resource. This distinguishes it from sibling tools like 'get_business_rule' (single rule) and the create/update variants. The purpose is immediately evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description only mentions a prerequisite (SCRIPTING_ENABLED=true) but does not explain when to choose this over 'get_business_rule' or how it differs from 'list_script_includes' or other listing tools. There is no exclusion or alternative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, which covers the safety profile. The description adds no additional behavioral context such as pagination, return format, ordering, or edge cases. It only restates the filter options already visible in the schema, offering minimal value beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that is front-loaded with the action and resource. It contains no redundant information and every word contributes to the purpose, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 3 optional parameters fully described in the schema and strong annotations. However, the description omits details like the meaning of the query parameter (encoded filter), defaults, or what the response contains. It is minimally adequate but not comprehensive for an agent operating without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (limit, query, state are all documented). The description mentions 'state or query' but does not add meaning beyond the schema; it omits the 'limit' parameter. With full schema coverage, the baseline of 3 is appropriate since the description adds little extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('change requests'), and the optional filters ('by state or query'). It distinguishes the tool from siblings like get_change_request, create_change_request, and update_change_request by the 'list' verb and focus on retrieval with filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing/filtering change requests but provides no explicit guidance on when to use this tool versus alternatives (e.g., get_change_request for a single record). It does not mention exclusions or alternative tools, so the usage context is only inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description does not need to confirm safety, and openWorldHint is provided. However, the description adds no behavioral context beyond the tool's purpose; it fails to mention the default limit (20) implied by the schema, nor does it clarify whether it returns all knowledge bases or only those accessible to the user. This is a notable gap for a listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the tool's function. It is well-structured and front-loaded with the action and resource, earning a maximum score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter, but the description lacks important context such as pagination behavior (the default limit) and the structure of returned data, especially since there is no output schema. While the schema provides the limit parameter, the description could be more explicit about what 'all' means given the limit, making it adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes the single 'limit' parameter with a clear description and default value, giving 100% schema coverage. The description does not add any parameter details, but since the schema is complete, the baseline of 3 applies. No extra semantic enrichment is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with the resource 'knowledge bases' and the scope 'available in the instance', clearly distinguishing it from sibling list tools. It precisely names the entity type, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is used when you need to enumerate knowledge bases, but it provides no explicit guidance on when to use it versus alternatives, nor any exclusions. There are many sibling list tools, but the description does not say 'use this for X, not Y'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 no extra behavioral context such as default limit, pagination, or scope of dashboards returned, but for a simple list operation with strong annotation coverage, this is minimally acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, 'List Performance Analytics dashboards', with zero wasted words. It is front-loaded with the key action and resource, making it easily scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity of the tool, the read-only annotation, and fully described optional parameters, the description is adequate but sparse. It does not mention what fields are returned or how to use the query/limit parameters, though these are in the schema. Lack of an output schema and minimal description leaves some room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for both parameters (limit and query), achieving 100% schema description coverage. The description itself adds no additional parameter meaning, so it does not exceed the baseline of 3 for tools where the schema carries the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and a clear resource 'Performance Analytics dashboards', which clearly distinguishes it from related sibling tools like 'get_pa_dashboard' that fetch a single dashboard. It directly states what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'get_pa_dashboard' or 'list_pa_indicators'. It lacks any mention of scenarios, prerequisites, or exclusions, leaving the agent to infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint, covering safety. However, the description's claim of listing 'all' configurations is contradicted by the limit parameter (default 25), and it does not disclose pagination or the fact that results are limited. This is a misleading behavioral trait not disclosed 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero wasted words. It clearly states the action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two optional parameters and good annotations, but the description leaves gaps: it fails to mention pagination/limit behavior, return format, or how it differs from other portal-related list tools. The 'all' claim is also inaccurate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters (limit and query), so the baseline is 3. The description adds no extra semantic meaning for the parameters, but the schema already sufficiently documents them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and a clear resource 'Service Portal configurations', with scope 'available in the instance'. It distinguishes this tool from sibling tools like list_portal_pages or list_portal_widgets by targeting configurations specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for enumerating Service Portal configurations, but does not explicitly state when to use this tool versus alternative list_portal_* tools, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds context by clarifying that these are custom apps installed in the instance, but it does not disclose return format, pagination behavior, or filtering defaults beyond the schema. This is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action verb and resource, with no wasted words. It is appropriately concise for a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple list operation, full parameter coverage, and readOnly annotations, the description is adequate. However, there is no output schema and the description does not clarify what fields are returned or whether inactive apps are included by default, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters (limit, query, active), so the schema already documents each parameter. The description does not add additional parameter-level meaning beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List scoped applications (custom apps) installed in the instance' uses a specific verb (List), identifies the resource (scoped applications / custom apps), and clarifies scope (installed in the instance). It clearly distinguishes from sibling tools like get_scoped_app, create_scoped_app, and update_scoped_app.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance or alternatives are provided. The tool name and description imply its use for listing scoped apps, but it does not mention when to prefer this over get_scoped_app or other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the safety profile is known. The description adds the existence of filters but does not disclose pagination, defaulting behavior, or response format. It provides minimal additional context beyond what annotations already cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, front-loading the verb and resource. Every word earns its place, and the structure is perfectly clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema and annotations cover the basics, the description lacks alternatives, default behaviors, and any mention of the response payload. For a simple list tool it is minimally adequate but not comprehensive; an agent would need to infer or inspect the schema for full usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all five parameters documented. The description redundantly lists three filter names but adds no new meaning about parameter formats, interactions, or the query parameter. Baseline of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with the resource 'security incidents' and names three filters (severity, state, category), clearly distinguishing it from single-record tools like get_security_incident. The scope is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_security_incident or list_vulnerabilities. The description does not mention any context, exclusions, or preferred use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description is consistent with those. It adds the context that subflows are 'reused across flows', but does not describe pagination, default limit, active-only filtering, or return format. Given the annotations cover the safety profile, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the essential purpose with no fluff or repetition. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple list tool with strong schema and annotations, but it lacks usage guidance and does not clarify whether the result includes all subflows or only those visible to the user. No output schema puts some burden on the description, which it does not fully address.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage for all three parameters (limit, query, active). The tool description adds no additional parameter details, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), the resource ('subflows'), and the scope ('available... that can be reused across flows'). This distinguishes it from sibling tools like create_subflow or get_subflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., list_flows or get_subflow). There are no exclusions, prerequisites, or explicit use cases beyond the generic 'list available subflows'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint: true and openWorldHint: true, so the description does not need to restate those. The description adds minimal context beyond the annotations, such as 'available', which hints at filtering by visibility. No behavioral details like pagination or return format are disclosed, but the annotations cover the main 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the core purpose without any fluff or redundant information. It is front-loaded with the verb 'List' and resource, making it easy to scan. The only minor issue is the typo 'macroponents', but it does not detract significantly from clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with two optional parameters and no output schema, the description is adequate. It communicates the resource and scope. However, it does not explain what the response contains or whether pagination is applicable, and the typo causes minor uncertainty. Given the low complexity and good annotations, this is a passable but not exceptional level of completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for both parameters (limit and scope), giving 100% coverage. The description does not add any additional semantics or examples beyond what the schema already states, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('UI Builder components'), and explicitly scopes it to 'in the instance'. This distinguishes it from sibling tools like list_uib_pages or list_uib_data_brokers, which target different resource types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention related tools like list_uib_pages or list_uib_data_brokers, nor does it specify any conditions that would make this tool the right choice. The usage is only implied by the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, so the read-only nature is already known. The description adds the 'recent' qualifier, which is a behavioral trait, but does not disclose return format, pagination, or default limits beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words. The description is highly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description could explain return value semantics or time range. However, the schema covers filter parameters and the operation is simple. The term 'recent' is ambiguous, but overall it is minimally adequate for a straightforward list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 no parameter-specific information; all meaning is already present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (recent Virtual Agent conversations). It distinguishes from siblings like get_va_conversation (retrieve single) and list_va_categories (categories).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_va_conversation. It simply states the action without explanatory context or explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is clear. The description adds useful methodology context (task durations and reassignment patterns) but does not disclose output format, data requirements, or any caveats. It is consistent with the read-only annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and efficiently conveys the tool's purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has two parameters, both documented, and annotations cover safety. However, with no output schema, the description omits what the result looks like (e.g., a list of bottlenecks, metrics), and it does not clarify what constitutes a bottleneck or how the output is presented. This leaves some gaps for an ML analysis tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in the schema (days with default 90, table with examples). The description does not add any additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('identify') and resource ('process bottlenecks') and explains the method ('analysis of task durations and reassignment patterns'). It clearly differentiates from sibling ML tools by targeting process bottlenecks, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when process bottlenecks need identification) but provides no explicit guidance on when not to use it or which alternative tools to consider. It neither mentions prerequisites nor exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to repeat safety. It does add context about the metrics covered (completion rates and fallback) but doesn't disclose other behavioral traits like aggregation periods or response structure. The bar is lower due to annotations, so a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence, front-loaded with the main purpose. Every word earns its place, no redundant filler. Ideal for a simple read-only analytics tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should clarify what the tool returns. It mentions two metric types but remains vague about output structure. For a read-only analytics tool with 2 optional parameters, the description is adequate but has clear gaps in return value expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both 'days' and 'topic_sys_id' have descriptions), and the description adds no additional parameter-level detail. The baseline of 3 applies since the schema handles parameter semantics adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Analyse' with a clear resource 'Virtual Agent NLU performance' and mentions concrete metrics (conversation completion rates and fallback metrics). It distinguishes from siblings by focusing on performance analytics rather than raw conversation lists, though it could be more explicit about the exact output format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for analyzing NLU performance, but provides no explicit guidance on when to use this tool over list_va_conversations or get_va_conversation, nor any exclusions or alternatives. The context among many VA-related siblings makes this a notable gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint and openWorldHint annotations already declaring the safety profile, the description adds useful behavioral details about supported operations (filtering, field selection, pagination, sorting). It does not contradict the annotations and provides context beyond what the annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently communicates the tool's core purpose and capabilities. Every word adds value, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple query tool with full schema coverage, but it mentions 'pagination' without a corresponding offset or page parameter in the schema, which could mislead. It also does not describe the return format, though the absence of an output schema makes this less critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 each parameter. The description only summarizes the parameter categories (e.g., filtering, sorting) without adding new format details, relationships, or usage nuances, placing it at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries ServiceNow records with filtering, field selection, pagination, and sorting, using a specific verb and resource. It differentiates from single-record tools like get_record by focusing on querying multiple records, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_record for single records or natural_language_query for AI-driven search. It only lists capabilities, leaving the agent to infer usage context from the tool name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, covering the safety profile. The description adds the mechanism 'reverting an update set,' which provides some behavioral context beyond the name, but does not mention consequences, reversibility, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the action and mechanism. There is zero wasted text, and the '[Write]' tag is redundant but harmless.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only 2 parameters, schema covers them fully, and annotations provide the destructive hint. The description adequately covers purpose and mechanism. However, it lacks any note on expected outcome or edge cases, which is a minor gap for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers both parameters with descriptions (100% coverage). The description itself does not add any extra meaning about the parameters, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Rollback a deployment by reverting an update set.' The verb 'rollback' and resource 'deployment' are explicit, and the mechanism 'reverting an update set' distinguishes it from generic rollback or other deployment tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like rollback_changes or validate_deployment. It does not mention any prerequisites, exclusions, or preferred use cases, leaving the agent without context to choose appropriately among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description doesn't need to restate safety. It adds minimal context by specifying that the tool returns dependencies and related CIs, but doesn't disclose depth, pagination, or any output format. This is consistent with annotations, so 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the purpose. No wasted words, perfectly concise for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, no output schema, and simple annotations, the description is minimally adequate. However, it doesn't describe what a 'summary' includes, how deep the dependency traversal goes, or what related CIs are returned. This could be complete enough for a basic usage, but there is room for more detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter (service_sys_id: 'System ID of the business service'). The description doesn't add additional meaning beyond the schema, which is the baseline case for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'View service dependencies and related CIs for impact analysis'. It specifies the verb 'View' and the resource (service dependencies and CIs). While it doesn't explicitly distinguish from sibling tools like cmdb_impact_analysis, the focus on 'summary' and dependencies is reasonably specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for impact analysis' implies a use case, but there is no explicit guidance on when to use this tool versus alternatives such as cmdb_impact_analysis or list_relationships. It does not mention exclusions or prerequisites, only a general context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only confirms a write operation via '[Write]', which is already indicated by readOnlyHint=false. It does not add behavioral context such as authorization requirements, side effects, or duplicate handling. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with just one substantive sentence and a clear write marker. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters and no output schema; the description is minimal but the schema's parameter descriptions and annotations provide additional context. However, it lacks guidance on overall usage flow, prerequisites, or what happens after recording, making it only moderately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All six parameters have schema descriptions with 100% coverage. The tool description does not add additional parameter semantics beyond that, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Record'), the resource ('deployment event in ServiceNow'), and the purpose ('audit and velocity tracking'). This distinguishes it from sibling tools like list_deployments, get_deployment, and rollback_deployment, which have different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context on what the tool does but does not explicitly contrast it with alternatives or provide when-not-to-use guidance. It doesn't mention other deployment tools, so the usage 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is a write (readOnlyHint=false), non-destructive (destructiveHint=false), and idempotent (idempotentHint=true). The description adds the requirement that WRITE_ENABLED must be true, which is useful context, but it does not disclose side effects or whether fields are merged or replaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence front-loads the action and prerequisite. No wasted words; concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with fully described schema and supporting annotations, the description is minimum viable. However, it does not mention what the tool returns or any validation/error conditions, which is a clear gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters (sys_id with 'System ID of the group' and fields with 'Key-value pairs to update') at 100% coverage. The description adds no additional parameter semantics, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Update a group' – a specific verb+resource that distinguishes it from siblings like create_group, get_group, add_user_to_group, and remove_user_from_group. The prerequisite is an extra detail, not confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives; only mentions the WRITE_ENABLED=true requirement. Does not note that it is for modifying existing groups as opposed to creating them or managing membership, nor does it reference sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds the WRITE_ENABLED=true requirement, which is useful, but provides no other behavioral context such as return value or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous information. It efficiently conveys purpose and a key requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two well-described parameters, but the description does not mention return value or behavior on failure. Given no output schema, some additional context would be beneficial, though the core update function is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both sys_id and fields. The description adds no additional meaning beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a scrum task' uses a specific verb and resource, clearly distinguishing it from create_scrum_task and list_scrum_tasks. It leaves no ambiguity about 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like update_task or create_scrum_task. The only added condition, 'requires WRITE_ENABLED=true', is a prerequisite, not a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description's mutation intent is consistent. It adds the WRITE_ENABLED=true precondition, which is useful context, but does not mention return values, partial update behavior, or error conditions. The added context is modest and does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that uses every word usefully, including the critical WRITE_ENABLED condition. No redundancy or padding exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two well-described parameters and safety annotations, but the description omits return-value behavior, error scenarios, and any distinction from complete_task or update_record. It is minimally viable but leaves meaningful gaps for an agent making an autonomous decision.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with sys_id and fields already explained. The description adds no further meaning beyond 'fields' and 'task record', so it remains at the baseline without compensating for any lack of schema detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Update fields') and resource ('task record'), which distinguishes it from related sibling tools like get_task or complete_task. The scope is concrete and aligned with the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite ('requires WRITE_ENABLED=true') but gives no guidance on when to use this tool versus alternatives such as update_record, complete_task, or more specific update_incident/update_change_request tools. No exclusions or alternative references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds only the '[Write]' tag, which merely restates the readOnlyHint: false annotation. It provides no additional behavioral context such as required permissions, side effects, or impact on mobile clients. The annotations already convey the safety profile, so the description contributes almost nothing beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus a tag, front-loaded and free of redundant text. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 params, 1 required), full schema coverage, and annotations covering the safety profile, the description is largely sufficient for tool selection. The lack of usage guidance and behavioral details prevents a perfect score, but these are adequately compensated by structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter (query, table, max_records) is already clearly described in the input schema. The tool description adds no parameter-specific details beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Configure' and identifies the resource 'which tables/records are available offline in mobile,' clearly distinguishing this from sibling mobile tools like create_mobile_app_config or list_mobile_app_configs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives. Usage is implied by the purpose and name, but no exclusions or alternative tools are mentioned, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the WRITE_ENABLED=true requirement, which is a behavioral prerequisite beyond the annotations. However, it doesn't disclose other behavioral traits such as what happens on success, whether an approval is triggered, or what the return value is.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that quickly states the action and a key prerequisite, with no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 15 parameters and no output schema, the description is too minimal. It doesn't explain what the tool returns, how the 'type' field affects behavior, or any post-creation steps. The WRITE_ENABLED hint is useful but insufficient for a complex creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 15 parameters are described in the input schema with 100% coverage. The description adds no additional parameter-level meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' with a clear resource 'change request', making the tool's purpose immediately obvious and distinct from sibling tools like update_change_request or list_change_requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite (WRITE_ENABLED=true) but does not explicitly mention when to use this tool instead of alternatives like update_change_request. The usage is implied by the verb 'Create', but there is no explicit exclusion or comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the WRITE_ENABLED=true requirement, which is not present in annotations, and it aligns with readOnlyHint=false by indicating a write operation. However, it does not disclose other behavioral aspects such as return values, error conditions, or the open-world nature of the schema, so it provides only partial context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, front-loading the action and a concise prerequisite. Every word earns its place, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward create operation with full schema coverage and annotations, the description is sufficient: it states the action and a key prerequisite. It does not explain output format, but that is not necessary given the simple nature of the tool and existing structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all four parameters with 100% coverage, including the required short_description and priority levels. The description adds no additional parameter semantics, so it does not exceed the baseline expected when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'problem record', making its purpose unambiguous. It is easily distinguishable from sibling tools such as get_problem, update_problem, and resolve_problem, which cover other lifecycle operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like create_incident or create_record. It only mentions the WRITE_ENABLED=true prerequisite but does not explain the appropriate context for choosing this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description includes '[Write]' to indicate it is a write operation, which aligns with the readOnlyHint=false annotation, and adds the side effect of route registration. However, it does not disclose permissions, error conditions, or reversibility. Beyond the annotation, only the route registration is new context, so it is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. 'Create a new UI Builder page with route registration' efficiently conveys the core action, and '[Write]' adds a useful side-effect hint without unnecessary length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with a well-documented schema, the description covers the core purpose adequately. However, with no output schema, it does not describe the return value, and it omits any mention of required permissions or how route registration interacts with the optional 'app' parameter. It is sufficient but has room for more detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage of all four parameters with descriptions, so the description does not add any additional parameter semantics. It does not explain defaults, relationships, or how parameters like 'app' and 'layout' affect the result beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('UI Builder page'), and adds 'with route registration' which distinguishes it from update/delete/list page tools and from component or route-only creation tools. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like list_uib_pages or update_uib_page. There is no mention of prerequisites (e.g., needing an existing UX app) or when not to use this tool. The description only states what it does, not when to choose it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint: false) and non-destructive (destructiveHint: false). The description adds the WRITE_ENABLED=true requirement, which is useful, but it does not explain side effects, return values, or error behaviors such as duplicate username handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly packed sentence that states the primary purpose and a key prerequisite. There is no fluff or repetition; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a create operation with no output schema, the description should disclose what is returned (e.g., sys_id of the new user), how duplicate usernames are handled, and any external side effects. The description is too thin to be fully self-sufficient, even with annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with clear descriptions (100% coverage), so the description does not need to add parameter details. The tool description contributes no additional parameter semantics beyond the schema, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the target ('a new user account'), which distinguishes it from sibling tools like update_user and list_users. The condition 'requires WRITE_ENABLED=true' adds useful context without obscuring the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly contrast this tool with alternatives, but the purpose strongly implies it is for creating new user accounts only. The WRITE_ENABLED condition is a prerequisite rather than guidance for when to choose this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's 'Get details' is consistent and adds little. It does mention 'including test count,' which is a useful detail about the response content, but doesn't disclose other behavioral traits or potential limitations. No contradiction found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is one short sentence (8 words) and front-loads the action and resource. Every word earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the tool is simple (1 param, read-only) and the description communicates the core return value (test count) plus general suite details. Given the annotations and schema coverage, it's mostly complete, though it could specify what other details are included or how to use the identifier.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for sys_id_or_name. The tool description adds no additional parameter semantics beyond the schema. Baseline 3 applies since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get details of a test suite including test count' with a specific verb (get) and resource (test suite). It distinguishes from siblings like get_atf_test (test, not suite) and list_atf_suites (list vs get) by its focus on single suite details with a count.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives such as list_atf_suites or get_atf_suite_result. The description only states what it does, not what distinguishes it or when to prefer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description aligns with this. The added requirement of SCRIPTING_ENABLED=true is valuable behavioral context beyond the annotations, disclosing a non-obvious precondition. However, it does not describe return details or error behavior, but the read-only nature is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the core purpose and the key prerequisite. Every word earns its place, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 one parameter and no output schema, the description is reasonably complete. It specifies the resource and the scripting prerequisite, but does not explain what 'details' are returned or differentiate from related update-set tools. The lack of output schema is partially mitigated by the intuitive nature of 'get details'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'sys_id_or_name' described as 'Update set sys_id or name'. The description adds no additional meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get details of an update set' clearly identifies the action (get) and resource (update set/changeset). It is specific but does not differentiate from sibling tools like list_update_sets or get_current_update_set, though the singular resource and 'details' imply a focused retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is the prerequisite 'requires SCRIPTING_ENABLED=true'. This gives a necessary condition but does not state when to use this tool versus alternatives like list_update_sets for enumeration or get_current_update_set for the active set. No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 a small behavioral detail by mentioning 'remaining time', which implies a computed field, but it does not disclose any other behavioral traits like data source, pagination, or potential latency. It adds some value but not rich context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that is front-loaded and free of redundant words. It conveys the full purpose without any waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 parameter and no output schema, the description sufficiently explains the tool's functionality. However, it does not specify the return format or mention differentiation from similar SLA tools, which is a minor gap. Overall, it is complete enough for a basic getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the only parameter (case_sysid) with a clear description. The tool description adds no additional parameter semantics beyond what the schema provides. With 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and clearly identifies the resource ('SLA details and remaining time for a CSM case'). It differentiates from sibling tools like get_sla_details (generic SLA) and get_csm_case (case details) by focusing specifically on SLA information for CSM cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_sla_details or list_active_slas. There is no mention of prerequisites, context, or exclusion criteria, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 the term 'status' which provides slight additional context beyond a generic 'get', but it does not disclose any other behavioral traits such as response format or filtering limitations. With annotations present, this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly conveys the tool's purpose without any unnecessary words. It is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 parameter and no output schema, the description is reasonably complete. It communicates that the tool returns details and status of a specific deployment, which covers the core need. It does not elaborate on response contents or edge cases, but given the low complexity, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the sys_id parameter described as 'Deployment sys_id'. The description adds no extra meaning beyond the schema, but since the schema already documents the parameter fully, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'deployment', specifying 'details and status' of a specific deployment. This distinguishes it from sibling tools like list_deployments (which lists all) and validate_deployment (which validates), 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as list_deployments or validate_deployment. The description simply states what the tool does without any context on prerequisites, exclusions, or alternative tools, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the read-only nature. The description adds no additional behavioral context (e.g., what fields are returned, error conditions, pagination), simply restating the tool's purpose without augmenting the annotation data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant information. It is appropriately sized and front-loaded, with every word earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 one required parameter and read-only annotations, the description adequately conveys the operation. It could mention what details are included or how to obtain the sys_id, but the tool's simplicity and strong schema make it sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents sys_id as 'Pipeline sys_id' with 100% coverage. The description does not add any further meaning or context about the parameter beyond what the schema provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Get' and identifies the resource as 'a specific DevOps pipeline'. It clearly distinguishes from siblings like list_devops_pipelines (which lists all pipelines) and get_deployment (a different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you have a sys_id to retrieve a single pipeline's details, but it does not explicitly state when to use it versus alternatives like list_devops_pipelines. There is no mention of obtaining sys_id from a list or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds some clarity by specifying that the result includes widgets/tabs, but it doesn't disclose any other behavioral details like pagination, error behavior, or permissions. This is a modest addition 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-front-loaded sentence that conveys the essential purpose without filler. Every word contributes to understanding the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool with no output schema, the description adequately communicates the main purpose and the key content of the response (widgets/tabs). However, it leaves 'details' somewhat open-ended and does not mention any limitations or return structure beyond that, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter sys_id_or_name with a clear description. The tool description does not add any additional meaning about the parameter, so it scores the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Get details' and the resource 'PA dashboard', and it specifies that the details include widgets/tabs. This clearly distinguishes it from sibling tools like list_pa_dashboards, which lists dashboards, and get_pa_indicator, which targets indicators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool instead of alternatives such as list_pa_dashboards or get_pa_scorecard. It only states what it does, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 covered. The description adds that layout is included, which is useful content detail, but provides no info on auth requirements or throttling. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with verb and object, zero filler. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one simple required param and no output schema, a single-sentence description is adequate. The detail about layout is a useful extra. Slightly above minimum viable due to including the layout aspect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with 'sys_id' described as 'Page sys_id'. The description adds no extra parameter meaning, but baseline is 3 because the schema fully covers it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches details of a specific Service Portal page including layout, with 'specific' and 'get' indicating a single-record read. It is distinguishable from siblings like list_portal_pages or get_portal_widget, though it doesn't explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need details/layout of one portal page, not for listing or creating. However, it doesn't explicitly state when not to use it or name alternatives, which is a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, which covers the safety profile. The description adds that it returns 'definition and metadata,' which is additional context beyond the annotations. However, it does not disclose behavior such as error handling, whether it returns a summary or full definition, or any limitations, so transparency is moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's function without any fluff. It is front-loaded with the key verb and resource, making it immediately scannable. No extraneous information is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, clear annotations), the description is reasonably complete. It explains what is returned (definition and metadata) and the parameter is fully documented. However, it could be slightly more descriptive about what 'definition and metadata' encompasses, such as whether it includes fields, permissions, or usage statistics. This would aid the agent in setting expectations, but the current text is sufficient for a basic get operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter, sys_id_or_name, with a clear description: 'Report sys_id or exact name.' Schema description coverage is 100%, so the description does not need to add parameter details. The tool description does not repeat or elaborate on the parameter, which is acceptable given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and identifies the resource as 'the definition and metadata of a saved report,' making it clear this tool retrieves a single report's metadata. This distinguishes it from sibling tools like list_reports, which lists reports, and create_report/update_report, which modify reports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. It implies usage through the purpose, but lacks any explicit guidance such as 'use this to fetch a specific report's definition; use list_reports to see all reports.' Without this, the agent has no direct cue for when this is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds the scoping constraint (specific task/incident) but does not disclose what the response contains or behavior for tasks without SLAs, which is acceptable for a simple read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and object, with no wasted words. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 parameter and good annotations, the description conveys the core purpose sufficiently. It does not describe the return format, but given the tool's simplicity and the presence of readOnlyHint, this is mostly complete. A 5 would require additional context about response shape or alternative use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for task_sys_id. The description reiterates that it's for a specific task/incident but adds no additional meaning beyond the schema, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with a clear resource 'SLA breach status' and scopes it to 'a specific task or incident', making it distinct from broader tools like list_active_slas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as list_active_slas or get_incident. The description only implies that a task_sys_id is needed, but does not explicitly state when 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true, covering safety and openness. However, the description adds no behavioral context beyond that, such as how missing properties are handled, permissions required, or the exact nature of the 'metadata' returned. Given the annotations, the lack of additional behavioral disclosure leaves a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and resource. No wasted words, and it is easily parsed by an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter getter with clear annotations. The description covers the essential purpose and parameter. The only missing piece is the exact return format or error behavior, but given the simplicity and the presence of annotations, the description is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'name' parameter, with an example (glide.smtp.host). The tool description adds nothing beyond the schema, so the baseline of 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and identifies the resource as 'ServiceNow system property' with scope 'by name', clearly distinguishing it from siblings like list_system_properties or search_system_properties. It is unambiguous and tells the agent exactly what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a specific property name is known, but it does not explicitly state when to use this tool vs alternatives like search_system_properties or list_system_properties. There is no direct guidance on exclusions or context, making it adequate but minimally directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and open-world. The description adds only that it retrieves 'configuration details' but does not disclose response structure, error behavior, or permissions, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no redundant wording. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with one parameter, the description is adequate, but it fails to specify what fields 'configuration details' includes or what happens on invalid input. Given no output schema, a bit more detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter sys_id_or_name with the note 'App sys_id or name' (100% coverage). The description adds no further parameter semantics, so it rests at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and resource 'configuration details of a Next Experience application', making the tool's purpose immediately clear. It differentiates from sibling list_ux_apps by targeting a single app's detailed config, though it doesn't explicitly name that alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives like list_ux_apps or get_workspace. There are no explicit conditions, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 that it returns 'conversation history', which is slightly more specific than the name, but does not disclose pagination, return format, or other behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that is concise and free of unnecessary detail. It earns its place by clearly stating the tool's purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, 2 parameters, and full schema coverage, the description is mostly complete. It could benefit from mentioning that it returns a chronological list of messages, but the name and 'history' make this highly inferable. The presence of sibling list_va_conversations also helps context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters (conversation_id and limit) fully described. The description does not add parameter-specific meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves conversation history for a Virtual Agent session, with a specific verb ('Get') and resource ('conversation history'). It distinguishes itself from the sibling 'list_va_conversations' by focusing on a single session's history rather than listing conversations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives like list_va_conversations. The description implies usage by mentioning 'for a Virtual Agent session' but does not provide conditions, exclusions, or references to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe, open read operation. The description adds that the tool focuses on maintenance and support contracts but does not disclose additional behavioral traits such as default filtering, pagination, or return format. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It is front-loaded with the verb and provides the core resource identifier. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple filtered-list tool with good annotations and fully described optional parameters, the description is sufficient. It clearly identifies the resource type without extraneous detail. While it does not explain return values, the absence of an output schema is mitigated by the straightforward nature of a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for limit, active, and asset_sys_id parameters. The description does not add any parameter-level meaning beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with the resource 'asset maintenance and support contracts', making it clear that this tool retrieves contract records for assets. This distinguishes it from sibling tools like list_assets and list_software_licenses, which operate on different resource types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives. There are no mentions of exclusions, prerequisites, or scenarios where another tool would be preferable. The intended usage is only implied by the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds that the tool returns 'current status', which is useful context. However, it does not disclose pagination behavior, ordering, or what 'current status' entails. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence, front-loaded with the verb, and contains no redundant information. It earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with fully documented parameters and read-only/open-world annotations, the description is largely sufficient. It could mention default behavior or how to use the state filter, but the schema covers parameters and the description clearly names the resource and output focus.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: limit and state both have clear descriptions. The tool description adds no additional parameter semantics beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('GRC compliance policies'), and adds 'their current status' to clarify the output includes status. This distinguishes it from sibling tools such as list_grc_risks, list_grc_controls, and get_compliance_assessment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention which scenarios call for list_compliance_policies instead of list_grc_risks or list_audit_results, nor does it note any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds scope ('used by notifications') but does not disclose additional behavioral traits such as pagination, search behavior beyond the schema, or default limits. This is acceptable given the read-only hint, but no extra context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the key action and resource. There is no wasted wording, and it is immediately clear what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with optional filters, the description, combined with the schema and annotations, is sufficient. It doesn't explain return format, but the lack of an output schema and the trivial nature of the operation make this acceptable; still, a bit more detail about what fields are returned could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with clear descriptions for 'limit' and 'query'. The description does not add any extra meaning about these parameters; it relies entirely on the schema, which is the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('email notification templates'), and clarifies their purpose ('used by notifications'). This clearly distinguishes it from related sibling tools like list_notifications and list_email_logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It doesn't mention exclusions or point to sibling tools like list_notifications for listing actual notification records, so the agent must infer usage solely from the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds no additional behavioral context such as result scope, pagination behavior, or error conditions. The 'List' verb merely restates the read-only nature without adding value beyond the annotation. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that immediately states the action and resource. It is front-loaded with the key verb and includes the GRC expansion, with no filler or redundant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with three optional filters and no output schema, the description, combined with the annotated schema, provides sufficient context for the agent to invoke the tool. However, it could mention the overall scope (e.g., 'all risk entries') or note that filters restrict the result set, but this is implied by the schema. It is adequate but not exceptionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each of the three parameters (limit, state, category) clearly described in the input schema. The description adds no parameter-specific information but does not need to, given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with a clear resource identifier 'GRC risk entries' and expands the GRC acronym. It distinguishes from siblings like get_grc_risk (single record) and create_grc_risk (write operation) because it names a listing operation. This is a clear, unambiguous statement of purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives such as get_grc_risk or list_grc_controls. Usage is only implied by the verb 'List' and the resource name. There are no exclusions or context about when filtering is beneficial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety and completeness profile. The description adds example categories but no additional behavioral context such as pagination, sorting, or result shape. It is consistent with annotations, so 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, efficient sentence that immediately communicates purpose and includes helpful examples. No redundant wording or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list tool with optional filters, the description is sufficiently complete. It accurately conveys the return type (templates) and scope (HR). While it doesn't describe the output format, the absence of an output schema makes that less critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all three parameters (limit, active, category). The description adds no parameter-specific semantic value beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('List') and resource ('available HR document templates') with concrete examples (offer letters, contracts, policies). This clearly distinguishes it from sibling HR tools like list_hr_tasks and list_hr_cases by specifying the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus other list tools, nor are any prerequisites or selection criteria mentioned. The description simply states what it does without contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is known. The description adds only the definition of OAuth applications, not any additional behavioral context such as pagination behavior, sorting, or filtering semantics beyond what the schema provides. It does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that is easy to parse and contains no filler. It efficiently conveys the tool's purpose and adds a clarifying definition without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with read-only annotations and well-documented parameters, the description is largely complete. It states the tool lists OAuth applications, which implies the return content. The only minor gap is the lack of explicit mention of default limit or result behavior, but the schema's limit parameter covers the default.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (limit, query), so the schema already documents their meaning. The description does not add any extra parameter-specific guidance, such as accepted formats or examples. Baseline 3 is appropriate when the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('OAuth application registry entries'), with a helpful parenthetical defining what those are ('client applications that can authenticate'). This distinguishes it from the many sibling list tools by specifying a unique resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention any context such as 'Use this to view registered OAuth clients' or exclude other tools. The intended usage is only implied by the action 'List', which is insufficient for a tool in a large catalog.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 returning all accessible records. The description adds the source table but reveals no additional behavioral traits such as pagination, ordering, or filtering rules beyond the default limit. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that states the exact action and target resource. No redundant words or filler, earning a perfect score for efficiency and directness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema, read-only annotations), the description provides enough context to understand what it does and what it lists. It could potentially mention the return format, but the name and schema cover the essentials, making this complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'limit' is fully described in the schema ('Max records to return (default 25)'), providing 100% coverage. The tool description itself adds no extra parameter meaning, so a baseline score of 3 is appropriate since the schema already carries the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists stored playbook definitions, specifying the source table 'sys_hub_action_type_definition'. This distinguishes it from sibling tools like 'list_process_automations' or 'list_flows' by naming the specific resource and table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. It does not mention executors, creation workflows, or indicate whether this is a prerequisite for actions like 'execute_playbook'. The description only states the basic function, leaving the agent to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, which the description aligns with. The description adds minimal behavioral context, such as the implied read-only nature of listing, but doesn't disclose additional traits like pagination or return details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no redundant wording. It's efficiently front-loaded and doesn't waste tokens.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with fully documented parameters and readOnly/openWorld annotations, the description is sufficient. It doesn't provide an output schema, but that's not required, and the description gives enough context for the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds no additional parameter semantics beyond what's already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List), the resource (pages), and the scope (belonging to a Service Portal). This distinguishes it from sibling tools like list_portals and list_portal_widgets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as get_portal_page or list_portals. The description only states what it does without any context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 a version note but discloses no extra behavioral traits like pagination behavior, included fields, or rate limits. With annotations present, this is acceptable but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence that is front-loaded with the primary action. The parenthetical endpoint note is extra but minimal. Every word earns its place, with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 with 100% schema coverage and readOnlyHint, the description is largely sufficient. However, it does not explicitly mention what fields are returned (e.g., report ID, name, category), and without an output schema this could be slightly incomplete. Still, the core behavior is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with descriptions for limit, search, and category. The description does not add any param-specific meaning beyond what the schema offers, hitting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List saved reports in the instance' with a specific verb and resource, distinguishing it from siblings like get_report (single report) and create_report. The added endpoint reference reinforces the resource scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives such as get_report for detailed report info or export_report_data. The description is purely functional and lacks any when-to-use or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate the safe read nature. It adds a small amount of context by specifying 'outbound' and 'external APIs', but does not disclose additional behavioral aspects like pagination, sorting, or return format. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the key verb and resource. It conveys the essential information without any fluff or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, full schema coverage, and readOnly/openWorld annotations, the description is adequate. It clearly identifies what the tool lists and the scope ('outbound', 'external APIs'). However, it could have mentioned that this is the list version complementing get_rest_message or list_rest_message_functions, so a small gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameters with descriptions ('limit' and 'query'), so the schema already provides the necessary meaning. The description adds no additional parameter semantics beyond what the schema offers, maintaining the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List outbound REST Message configurations'. It uses a specific verb and resource, and adds clarifying context that these are 'integrations with external APIs', which distinguishes it from sibling tools like list_rest_message_functions or get_rest_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as list_rest_message_functions or create_rest_message. It does not mention any specific use cases, exclusions, or scenarios where another tool would be better suited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds domain context (data brokers are data sources for pages) but no behavioral detail beyond what annotations already provide. readOnlyHint and openWorldHint already indicate a read-only, open-world operation. The description doesn't disclose pagination, return format, or filtering semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. It concisely states the action and resource, making every word valuable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a list operation with two optional parameters and no output schema, the description gives minimal context about return shape or limit usage. It's adequate for a simple listing but leaves gaps around result structure and pagination, which are not covered by annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: page_sys_id is documented, but limit is not. The description itself doesn't mention or explain any parameters. It adds no semantic value for limit, leaving it solely defined as a number with no context, and page_sys_id is only explained in schema, not reinforced here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies a distinct resource type 'UI Builder data brokers', with a clarifying parenthetical '(data sources for pages)'. This clearly distinguishes it from siblings like list_uib_pages or create_uib_data_broker.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance is given. The parenthetical implies the tool is for enumerating page data sources, but there are no alternatives or exclusions mentioned. Usage is only implied, not explicitly clarified in relation to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, positioning this as a safe read operation. The description adds a small detail about returning route configurations, but does not disclose pagination behavior, default limits, or potential large result sets. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that starts with the action verb and resource. Every word contributes meaning, with no redundancy or excess.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional parameters and no output schema, the description adequately conveys the core function and the nature of returned data (route configurations). It could mention pagination or filtering capabilities, but the schema covers the parameters. Overall, sufficient for this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (app and limit) are already documented in the input schema. The description adds no additional parameter context beyond the resource type. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and clearly identifies the resource ('UI Builder pages') plus additional detail about what is included ('route configurations'). It distinguishes from sibling tools like list_portal_pages and list_uib_components by explicitly naming UI Builder pages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. With sibling tools like list_ux_pages and list_uib_components, the description does not clarify the intended use case or exclusions. The purpose is implied only by the name, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is known. The description does not add any additional behavioral context beyond 'list', but it is consistent with annotations and does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise phrase with no wasted words. It is front-loaded with the action and resource, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 adequately conveys the tool's purpose. It does not explicitly mention filtering or return format, but the schema covers parameters, and the context is sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (limit, query) fully described. The description adds no extra parameter context, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List) and the specific resource (Next Experience UI Builder applications). It distinguishes from sibling tools like list_ux_pages and get_ux_app by focusing on applications rather than pages or a single app.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_ux_app or list_ux_pages. The description only states what the tool does, not when it should be chosen.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (readOnlyHint: true, openWorldHint: true) by indicating a read-only list operation. However, it adds no extra behavioral context such as pagination behavior, return format, or that openWorldHint implies results may be incomplete. With annotations already covering safety, the description adds minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded and free of any redundant information. Every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter, no output schema, and annotations providing safety hints, the description is mostly complete. It lacks explicit mention of the return format or that categories may be limited by the openWorldHint, but the low complexity makes these omissions acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents the only parameter 'limit' with its description 'Max results (default 25)', achieving 100% schema coverage. The description does not add any additional parameter semantics, so the baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Virtual Agent topic categories' uses a specific verb ('List') and resource ('Virtual Agent topic categories'), clearly distinguishing it from siblings like list_va_conversations (conversations) or list_va_topics_full (topics). It directly states 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention that it is specifically for categories, nor does it advise against using list_va_topics_full when full topic details are needed. The description leaves the usage context entirely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds that it returns accuracy, training status, and metrics, which is helpful context, but does not disclose any additional behavioral traits such as dependencies or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
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 wasted words. It earns every character.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description adequately conveys what is returned. However, 'metrics' is somewhat vague and could be more specific about the return structure, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for model_sys_id with a description. The tool description does not add any param-specific context beyond what the schema already states, so it does not exceed the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves accuracy, training status, and metrics for a trained ML solution. It uses a specific verb ('Get') and resource ('trained ML solution') but does not explicitly differentiate from sibling ML tools like ml_model_training_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for a trained ML solution' implies the tool should be used after training, but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false), but the description adds the prerequisite that SCRIPTING_ENABLED must be true, which is useful context. It also mentions the output format 'XML for deployment', providing some behavioral detail beyond the annotations, though it does not describe side effects or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose ('Publish/export an update set to XML for deployment') and includes the prerequisite. Every word earns its place, with no unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, full schema coverage, and no output schema, the description provides sufficient context: purpose, output format (XML), and a system requirement. It does not describe return structure, but given the simplicity and annotations, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single required parameter (sys_id) with a clear description. The tool description does not add any additional meaning or syntax for parameters, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Publish/export an update set to XML for deployment.' This is a specific verb and resource, distinguishing it from update set management tools like list_update_sets or switch_update_set. However, it does not differentiate from the similarly named 'export_update_set' sibling, so it lacks explicit sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context that the tool is for deployment and includes a prerequisite ('requires SCRIPTING_ENABLED=true'), which gives some usage guidance. However, it does not explicitly say when to use this tool versus alternatives, nor does it mention when not to use it, so guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the write nature is known. The description adds the WRITE_ENABLED=true environmental constraint, but does not disclose behavioral details like state transition (e.g., marking the problem as resolved) or potential side effects. It adds some value beyond annotations but remains thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and resource, then adds a necessary requirement in parentheses. Every word earns its place with no unnecessary filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no output schema) and existing annotations, the description covers the core purpose and the key prerequisite. It could be more explicit about the effect of resolving (e.g., setting the problem to a 'Resolved' state), but overall it adequately supports selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have schema descriptions covering their meaning, so the baseline is 3. The description mentions 'root cause and resolution notes' which reinforces the schema but does not add new semantics. No additional detail on formats, allowed values, or relationships between parameters is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Resolve a problem') and the resource ('problem'), with specific context ('root cause and resolution notes'). It distinguishes from sibling tools like create_problem, get_problem, and update_problem by focusing on the terminal 'resolve' action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like update_problem or resolve_incident. The only non-obvious detail is the WRITE_ENABLED=true requirement, which is a prerequisite rather than a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral detail beyond what the annotations already convey. It does not mention side effects, return values, or any prerequisites. Since the annotations already indicate this is not read-only, not destructive, and idempotent, the description provides no additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the tool's purpose without any filler or repetitive content. It is appropriately sized for the simple action it describes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and annotations present, the description adequately states the action. It is a lightweight context-switching operation, so the minimal description is sufficient, though it omits any mention of error behavior or effects on the environment beyond the obvious.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the only parameter (sys_id) with its description. The tool description adds no extra meaning or context around the parameter, so it does not exceed the schema's coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Switch') and clearly identifies the resource ('active Update Set context') and action ('to a specified Update Set'). It distinguishes this tool from sibling tools like get_current_update_set and ensure_active_update_set by stating the precise operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage through the action described, but provides no explicit guidance on when to use this tool versus alternatives such as ensure_active_update_set or list_update_sets. No exclusions or when-not-to-use conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds 'time-bucketed' but doesn't disclose output structure, aggregation behavior, or limitations. It 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. It effectively communicates the core purpose without wasting words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should clarify what the trend data looks like (e.g., time buckets with counts). It doesn't explain the role of periods or query filters beyond the schema, leaving a meaningful gap for a 5-param tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with clear descriptions. The tool description adds no additional parameter semantics, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets time-bucketed trend data for a table and even provides a concrete use case (monthly/weekly trend charts). This specific verb+resource combination distinguishes it from generic query tools like query_records or visualize_trend.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for trend charts, but it doesn't explicitly state when to prefer this over alternatives (e.g., query_records, run_aggregate_query) or provide exclusions. It's a helpful hint, but not full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive, idempotent write operation. The description adds the prerequisite that WRITE_ENABLED=true is required, which is useful operational context. However, it doesn't disclose behavior when the flag is false or describe edge cases like non-existent items, so it provides limited additional transparency 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to the meaning, and the parenthetical requirement is concise. It earns a top score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with two fully-described parameters and no output schema, the description plus annotations provide adequate context. It mentions the WRITE_ENABLED prerequisite, and the schema covers the parameters. It doesn't explicitly explain partial update semantics, but the nested 'fields' object implies it. Overall, it's reasonably complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% with both 'sys_id' and 'fields' described. The description adds no parameter-level detail beyond what the schema already provides, so the baseline score of 3 for high schema coverage is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing catalog item' uses a specific verb and resource, clearly indicating a modification operation. It distinguishes from create_catalog_item and get_catalog_item by virtue of the 'update' verb, but it doesn't explicitly differentiate from the generic update_record tool, so it's not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for existing catalog items that need modification, but it doesn't explicitly state when to use this tool versus alternatives like create_catalog_item or update_record. No exclusions or alternative names are provided, making the guidance only 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose that the tool writes (readOnlyHint=false) and is non-destructive and idempotent. The description adds the WRITE_ENABLED requirement, which is useful environment context, but does not describe side effects, error behavior, or what happens if the article is not found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It front-loads the action and includes the only critical prerequisite in a parenthetical, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain return values or success/failure behavior, but it does not. It also does not mention whether the update replaces or merges fields, or if the article must be in a particular state. This leaves significant gaps for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both sys_id and fields. The description adds no additional parameter context beyond the schema, so it earns the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Update' and a clear resource 'knowledge article'. It distinguishes this tool from siblings like create_knowledge_article, publish_knowledge_article, and retire_knowledge_article by implying the action is modifying an existing article.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite (WRITE_ENABLED=true) but does not explicitly state when to use this tool versus alternatives like create_knowledge_article or publish_knowledge_article. The usage context is implied by the verb 'update' but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the WRITE_ENABLED=true prerequisite, which is not captured in the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). However, it doesn't disclose other behavioral details such as partial update semantics, error behavior on nonexistent user, or permission requirements, leaving the agent to infer from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, front-loading the operation and the key prerequisite. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter operation, full schema coverage, and annotations indicating safety properties, the description is reasonably complete. It lacks explicit usage guidance, but that is penalized in the usage dimension; the core operation and prerequisite are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for sys_id and fields, so the baseline is 3. The description adds no parameter-level semantics beyond what the schema already provides; the 'fields' object is adequately described as key-value pairs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' and resource 'user account', clearly distinguishing from sibling tools like get_user, create_user, and list_users. It also adds the WRITE_ENABLED prerequisite, making the operation unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to prefer this tool over alternatives like update_record or natural_language_update, nor does it mention that it's for existing users only. The only usage hint is the WRITE_ENABLED requirement, which is a precondition rather than a selection guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds only a redundant '[Write]' tag, which duplicates the annotation readOnlyHint=false. No additional behavioral context is provided, such as partial update semantics, error behavior, or authorization needs. Annotations already cover the safety profile, so the description adds no value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, a single sentence plus a short tag. It is front-loaded with the action and resource, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with full schema coverage and annotations, the description is mostly complete. However, it does not specify return value or behavior when sys_id does not exist, which could be useful. Given the simple nature, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (sys_id and fields). The description adds no parameter-specific meaning beyond what the schema already provides, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates Virtual Agent topic properties with a specific verb ('Update') and resource ('Virtual Agent topic properties'). This distinguishes it from sibling tools like create_va_topic and get_va_topic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the 'update' verb, but there is no explicit guidance on when to use this tool vs alternatives (e.g., create_va_topic for new topics). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint:false, destructiveHint:false), the description adds only '[Write]', which is redundant. It does not disclose non-idempotency, validation rules, or what the response contains. No additional behavioral context is offered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence plus a minimal '[Write]' marker. It is front-loaded with the primary purpose and contains zero unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with full schema coverage and annotations, the description is minimally adequate. However, it does not mention that each call creates a distinct record, possible return values, or any prerequisites beyond the schema, leaving a moderate gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes all 6 parameters with full coverage (100%), including names and descriptions. The tool description contributes nothing about parameters, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new GRC risk entry' uses a specific verb and resource, clearly distinguishing it from sibling tools like list_grc_risks and get_grc_risk. There is no ambiguity about what operation this performs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly name alternatives or exclusions, but the create verb and the sibling set (list/get only) make it clear this is the tool for adding a new risk. Context is clear, though no direct comparison is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a non-read-only, non-idempotent, non-destructive operation, so the baseline is lower. The description adds the WRITE_ENABLED=true prerequisite, which is useful environmental context, but it does not disclose return behavior, side effects beyond creation, or what happens without required fields. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, tightly packed with essential information: action, resource, parent relationship, and a key prerequisite. Every word earns its place, with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (3 params, no output schema, annotations present), the description is mostly adequate but leaves some gaps. It does not clarify why story_sys_id is optional despite calling the task a sub-task of a story, nor does it mention what the tool returns or how the WRITE_ENABLED flag affects execution. A bit more context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents all three parameters. The description adds no additional parameter meaning beyond what the schema provides, but it does not need to; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the specific resource ('scrum task') with a clarifying parenthetical that it is a sub-task of a story. This distinguishes it from siblings like create_story and update_scrum_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through its clear create intent but does not explicitly state when to use it versus alternatives (e.g., update_scrum_task for modifications) or when not to use it. The WRITE_ENABLED prerequisite is a useful condition but does not substitute for explicit usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and idempotentHint=false, so the write nature is covered. The description adds 'configurable' as a trait but does not elaborate on side effects, permissions, or what happens on repeated calls. Minimal additional behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It immediately states the action and resource, and the '[Write]' tag is a brief, useful addition. Exemplary conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (4 parameters, no nested objects, no output schema), the description is adequate but not rich. It does not mention return values, prerequisites, or idempotency caveats, which could be relevant for a create operation. It provides the minimum needed to understand the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, meaning most parameters are documented in the schema itself. The description does not add meaningful parameter semantics beyond the schema. The 'configurable' hint is too vague to compensate for the undocumented 'description' parameter, but the schema handles most of the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'Create' with a clear resource 'agent workspace' and qualifier 'configurable', distinguishing it from sibling tools like list_workspaces or get_workspace. It explicitly indicates the action and object in a concise manner.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The verb 'Create' implies usage for new workspace creation, but the description does not provide explicit context on when to use this tool versus alternatives such as configure_workspace_list or update-related tools. No exclusions or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds some behavioral context beyond annotations by explaining that results are passed forward in a step-by-step manner and that dry_run is supported. However, it doesn't disclose that executing a playbook will invoke other tools and may cause side effects, which is significant given readOnlyHint=false and openWorldHint=true. It also omits information about how errors are handled or what happens on actual (non-dry-run) execution.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core action, key behavior, a prerequisite, and a notable feature (dry_run). Every phrase earns its place with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the playbook object and the absence of an output schema, the description is somewhat incomplete. It covers the primary purpose and important behavioral notes, but it doesn't explain execution semantics such as how steps invoke tools, how on_error and condition affect flow, or what the result format looks like. The schema provides detailed structure, but the description still leaves gaps for a complex orchestration tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description adds minimal semantic value by correlating 'passing results forward' with the context parameter and highlighting dry_run support, but it doesn't provide new syntax or format details. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Execute') and resource ('a playbook'), and adds how it works ('step by step, passing results forward through context'). It distinguishes itself from sibling tools like create_playbook and list_playbooks by focusing on execution, and from run_security_playbook by being general-purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for executing a playbook and mentions a prerequisite ('requires NOW_ASSIST_ENABLED'), but it provides no explicit guidance on when to choose this over other automation tools (e.g., run_flow, trigger_flow) or when not to use it. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the specific operational requirement 'requires WRITE_ENABLED=true', which is useful context beyond the annotations. However, it does not disclose potential side effects (e.g., event handlers may run asynchronously), non-idempotency, or what happens after firing. Since annotations already indicate non-read-only and non-idempotent behavior, the added context is modest but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core action ('Fire a custom ServiceNow event') and adds a relevant prerequisite. Every word contributes value with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with the schema, covers the essentials: what to fire, on which record, and the write-enabled prerequisite. However, there is no output schema and the description does not explain return values, asynchronous behavior, or side effects. It is minimally viable but leaves gaps for an agent trying to reason about consequences.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the description does not need to restate field semantics. The description adds no additional meaning beyond the schema, but the schema already documents all five parameters adequately. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Fire a custom ServiceNow event for a specific record.' It uses a concrete verb and resource, and the 'custom event' + 'specific record' language distinguishes it from related tools like register_event or list_event_registry. The purpose is immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to fire a custom event on a record) but does not explicitly state alternatives or when-not-to-use scenarios. The only guidance is the prerequisite 'requires WRITE_ENABLED=true', which is a condition rather than a usage guideline. No sibling tools are mentioned as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds return behavior ('Returns records or aggregate results') and a concrete example, providing value beyond annotations. It does not contradict annotations, though it does not detail pagination or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences and a compact example. It front-loads the purpose, lists supported features, states the return type, and gives an illustrative usage. No waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool with 10 parameters and no output schema. The description covers core query operations and includes an example, but it does not explain aggregate query construction in depth or provide guidance on selecting this tool over sibling query tools. Given the rich input schema, it is reasonably complete, though not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema provides full parameter documentation. The description adds a working example demonstrating parameter combinations (where, select, limit), which enhances understanding beyond the schema alone. Some parameters like orWhere and displayValue are not mentioned in the description, but the schema already covers them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly identifies the tool as a 'GlideQuery-style fluent query builder' and lists supported operations (select, where, aggregate, orderBy, limit, groupBy) and return types. However, it does not explicitly differentiate from sibling query tools like query_records or run_aggregate_query, so it falls short of full distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as query_records, run_aggregate_query, or nlq_query. There are no exclusions, prerequisites, or contextual hints to help an agent choose between similar query capabilities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and open-world, and the description does not contradict them. It adds the event-type scope, but does not disclose pagination behavior, ordering, or return structure, so it provides only modest extra transparency 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that uses no filler. Length is appropriate for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 mostly adequate, but it omits onboarding and offboarding from the event-type examples even though the schema includes them, which could mislead. It also doesn't clarify the return format, though no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema documentation covers 100% of parameters with descriptions for limit, event_type, and employee_sys_id. The description's mention of event types largely duplicates schema info and adds no new parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the operation ('Get') and the resource ('HR lifecycle events for an employee'), and lists representative event types (promotions, transfers, leaves). This distinguishes it from sibling HR tools focused on cases, tasks, or profiles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving employee lifecycle events but provides no explicit guidance on when to use it over related HR tools like list_hr_tasks or get_hr_case. No exclusions or alternative references are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate a read-only, open-world operation, so the safety profile is well covered. The description adds that the tool analyzes usage and produces recommendations, but it does not disclose details such as what data sources are consulted, whether it is based on historical usage, or any other behavioral nuances 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action ('Analyze software license usage') and clearly states the outcome ('recommend optimizations'). It contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a high-level purpose but does not explain the returned output structure, any requirements, or how threshold_pct affects the analysis. Given there is no output schema, the absence of return format details leaves the agent without a complete picture of what the tool will deliver.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters (software_name and threshold_pct) are fully described in the input schema with meaningful descriptions, and the schema coverage is 100%. The description does not add any additional parameter semantics, which is acceptable given the schema already provides complete information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: 'Analyze software license usage and recommend optimizations.' The verb 'analyze' and the objective 'recommend optimizations' distinguish it from sibling tools like list_software_licenses (listing) and get_license_compliance (compliance status), so the purpose is specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. It only states what it does, without mentioning preconditions, exclusions, or alternative tools, so usage is implied from the name and description rather than explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, which align with 'look up'. The description adds the behavior of looking up by email or username but does not disclose return format, not-found handling, or whether the lookup is exact. With annotations covering safety, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action and resource. There is no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema, so the description bears some responsibility for return values. It does not state what user details are returned or error behavior, but annotations and parameter description cover invocation. It is adequate for a basic lookup but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the user_identifier parameter with description 'Email address or username', and schema coverage is 100%. The description essentially restates what the schema provides without adding extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'look up' and identifies the resource 'user details', making the purpose clear. Mentioning lookup by email or username distinguishes it from sibling tools like list_users or get_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching a single user by identifier, but does not explicitly state when to use this over alternatives like list_users or search tools. It provides clear context but no exclusions or explicit alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true. The description adds minimal behavioral context beyond restating that attachments are associated with a record; it does not disclose return format, pagination, or other operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundant or extraneous information. It is efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and annotations cover safety, but without an output schema or description of return values, the agent lacks full context about what the list contains. The description is adequate for basic intent but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond what the schema already specifies for table, record_sys_id, and limit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with the resource 'attachments' and scopes it to 'a specific record'. This clearly distinguishes it from sibling tools like upload_attachment, delete_attachment, and get_attachment_metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context that this tool is for listing attachments for a specific record, which indicates when to use it. However, it does not mention alternatives or exclusions, so it falls short of explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and openWorldHint. The description adds that tasks are scoped to a parent HR case, but does not disclose additional behavioral traits such as ordering, pagination, or filter semantics beyond the schema's state parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that directly states the tool's purpose without redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool and the schema covering parameters, the description is adequate, but it leaves out any details on return structure or limits, which could be expected for a listing operation. No output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes both parameters (hr_case_sysid and state) with 100% coverage. The description adds no additional parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and identifies the resource 'HR tasks' plus the scope 'associated with an HR case', clearly distinguishing it from sibling tools like list_hr_cases or get_hr_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context—listing tasks for a specific case—but does not explicitly mention when to use it over alternatives such as list_my_tasks or get_hr_case_activity. No exclusion guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint annotation and adds that run schedules are included in results, but it does not disclose details like pagination behavior, response structure, or how filters (limit, query, active) affect output. The annotations already convey safety, so the bar is lower, but the description adds limited extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose. Every word is informative, with no redundant phrases or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should help the agent anticipate the return shape. It mentions 'run schedules' which gives some idea, but it does not mention defaults, pagination, or the effect of the 'active' parameter. For a simple list tool, the description is adequate but leaves some behavior unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters (limit, query, active), including defaults. The description adds no additional parameter semantics beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and identifies the resource 'scheduled jobs' with the additional scope 'their run schedules'. This clearly distinguishes it from related tools like get_scheduled_job (single record) or trigger_scheduled_job (mutation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied as a general listing tool, but there is no explicit guidance on when to use this over alternatives like list_job_run_history or get_scheduled_job. No exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, covering the safety profile. The description adds context that it is specifically about widget instances on portal pages, but it does not disclose pagination behavior, return format details, or any filtering nuances beyond what the schema offers. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately communicates the tool's purpose with no redundant information. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and annotations cover safety, but there is no output schema and the description does not clarify what the returned instances will contain (e.g., page names, sys_ids, properties). The agent can infer it returns a list of widget instance records, but the lack of return-structure detail makes it only adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description adds no additional semantic meaning beyond the schema, but the parameter names and schema descriptions are self-explanatory. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clear resource ('instances of a specific widget placed on portal pages'). It distinguishes from siblings like list_portal_widgets (which lists widget definitions) and get_portal_widget (which gets a single widget), specifying that this tool finds widget placements across portal pages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to find where a widget is placed on portal pages, but it does not explicitly state when to use this versus alternatives, nor does it mention exclusions or prerequisites. It is a clear but minimal indication of purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true, the description only needs to add context beyond the safety annotation. It adds 'based on historical trends', which is useful but does not disclose details like response variability, data prerequisites, or internal model dependencies. The description does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded with the primary action and resource, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description does not hint at the return format (e.g., a time series or single number). It also omits information about the source of historical trends or any assumptions. While the tool is simple and annotations cover safety, this feels slightly under-specified for a forecasting tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% since each parameter (category, priority, days_ahead) has a description. The tool description's 'next N days' aligns with days_ahead but adds no additional meaning beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Forecast'), the resource ('incident volume'), and the temporal scope ('next N days'). It distinguishes itself from sibling ML tools like ml_predict_change_risk and ml_detect_anomalies by focusing specifically on incident volume forecasting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for forecasting incident volume, but it does not provide explicit when-to-use vs alternatives guidance. There are no exclusions or named alternative tools, making the usage context only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and not idempotent. Description adds that it 'triggers training', which implies a state change, but does not disclose potential async behavior, resource impact, or effects on existing model versions. This is acceptable given annotation coverage but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single clear sentence, directly front-loaded with verb and object. No filler or redundancy; the trailing '[Write]' is a separate classification, not part of the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no output schema and one optional param. Description covers the core action but does not mention what the response looks like, whether training is synchronous or asynchronous, or if any confirmation/job ID is returned. Given the simplicity, this is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a self-descriptive parameter 'solution_name' (default auto-detect). Description adds no parameter info, but the schema already sufficiently documents the single optional parameter, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Trigger training' and identifies the exact resource 'change risk prediction ML model'. It clearly distinguishes from sibling tools like ml_predict_change_risk or ml_train_anomaly_detector by naming the model type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage: call when you need to train/retrain the change risk model. However, no explicit when-to-use or alternatives are mentioned, such as using ml_predict_change_risk for prediction or ml_evaluate_model for evaluation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag this as a non-read-only, non-idempotent operation. The description adds the WRITE_ENABLED=true prerequisite, which is useful, but it does not disclose side effects like creating a request, triggering approvals, or what response to expect. With annotations covering the safety profile, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that states the action and a key requirement. Every word earns its place; there is no wasted text or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutative, open-world action with no output schema, the description lacks context about the result (e.g., what is returned, whether a request is created). The 100% param coverage helps, but the tool's external effects and response format are left unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters (sys_id, quantity, variables) are already documented. The description adds no extra parameter meaning beyond what the schema provides, so baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource combination ('Order a service catalog item') that clearly distinguishes it from sibling tools like create_catalog_item, get_catalog_item, and update_catalog_item. The action is well-defined and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you want to order a catalog item) but does not explicitly state when to prefer this over alternatives like create_catalog_item or search_catalog. It only provides a prerequisite (WRITE_ENABLED=true), not usage context or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states a write operation ('write edited fields back' and 'Overwrites the listed fields') while annotations declare readOnlyHint=true, which means the tool is supposedly read-only. This is a direct annotation contradiction, so the score must be 1 per the rules.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and every clause adds value (write action, prerequisites, no-merge behavior, conflict detection). No redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers prerequisites, core behavior, conflict handling, and parameter usage, but the annotation contradiction leaves side effects ambiguous. It also omits the return value or error behavior, and with no output schema, the agent is left without a complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are already documented. The description restates the dual-mode behavior of 'fields' and the conflict-abort purpose of 'expected_updated_on', but does not add significant new meaning beyond the schema, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Local sync: write edited fields back to an artifact', which clearly states a specific verb ('write') and resource ('artifact'). It distinguishes itself from siblings like pull_artifact by referencing 'pulled files' and 'sync_status', 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'requires WRITE_ENABLED=true', 'run sync_status first', and 'pass expected_updated_on to abort' if the record changed. It also explains the two modes of parameter passing (inline fields vs on-disk files), leaving no doubt when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is not read-only, not destructive, and not idempotent, and the description adds the WRITE_ENABLED=true requirement. However, it does not explain side effects (e.g., data insertion/update into target tables), potential failures, or execution behavior. The description adds some value beyond annotations but remains minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a parenthetical note. It is front-loaded, concise, and every word contributes information. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 2 params, minimal annotations, and no output schema, the description gives the core action and a key prerequisite, but lacks information on expected outcomes, error scenarios, or other requirements. It is minimally viable but leaves gaps for an agent deciding whether to invoke and what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters described in the schema. The description does not add any additional semantic meaning about the parameters, and the schema already provides the necessary context. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Execute', the resource 'Transform Map', and the object 'Import Set', with the intent 'to load data'. This distinguishes it from siblings like get_transform_map and list_import_sets, which are read-only retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'to load data' implies when to use the tool, but there is no explicit guidance on when not to use it or mention of alternatives. The requirement 'WRITE_ENABLED=true' is a prerequisite but not a usage guideline. No exclusions or alternative tools are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false), and the description adds the WRITE_ENABLED prerequisite, which is useful. However, it does not disclose whether the flow runs synchronously, returns an execution ID, or what side effects occur. The description goes slightly beyond annotations but lacks richer behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and includes a key prerequisite. Every word earns its place; no redundant or vague phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and the description does not explain what happens after triggering (e.g., whether it returns an execution ID or how to retrieve execution status). Given the existence of sibling tools like get_flow_execution, a more complete description would mention the expected return or follow-up. The description covers the basics but leaves operational gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers both parameters with descriptive text (flow_sys_id as 'sys_id of the flow to trigger' and inputs as 'Key-value pairs for flow input variables'). The description's mention of 'optional input parameters' adds minimal semantic value, aligning with the baseline for 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Trigger a Flow Designer flow with optional input parameters.' It identifies the specific resource (Flow Designer flow) and verb (trigger), distinguishing it from siblings like get_flow or list_flows which merely inspect metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a prerequisite ('requires WRITE_ENABLED=true') but does not explicitly contrast with alternatives such as test_flow or mention when to use this instead of other flow-related tools. The usage context is only implied by the action of triggering, without exclusions or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) that is idempotent and non-destructive. The description adds the prerequisite that WRITE_ENABLED=true must be set, which is useful context, but it does not disclose behavioral details such as whether the update is partial or full, or what the return value is.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence ('Update fields on a change request') with a necessary parenthetical about the WRITE_ENABLED flag. Every part serves a purpose, and there is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with full schema coverage, but the description omits key context such as whether only the specified fields are updated, the return value, and any side effects. Given the absence of an output schema, the agent cannot know what the tool returns, leaving a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters, with descriptions for 'fields' and 'sys_id' already provided. The description adds no additional parameter semantics beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') with a clear resource ('fields on a change request'), distinguishing it from sibling tools like create_change_request, get_change_request, and close_change_request. The phrase 'requires WRITE_ENABLED=true' adds a constraint but does not obscure the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when updating fields on an existing change request, but it does not explicitly state when to use it over alternatives such as create_change_request or close_change_request. There is no mention of exclusions or alternative tools, leaving the agent to infer usage from the name and verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-readonly, idempotent, non-destructive operation. The description adds the WRITE_ENABLED=true requirement, which is useful auth context. However, it does not disclose return values, error behavior, or side effects 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the action and includes the prerequisite in parentheses. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete enough for a simple update operation with full schema coverage and annotations, but it does not explain return values or allowed field keys, which could be ambiguous for an agent. It is adequate but not detailed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters clearly described. The tool description adds minimal semantic value beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates fields on an existing HR case, using a specific verb and resource. It distinguishes from creation (existing) and closure tools, and includes a prerequisite requirement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for existing HR cases and specifies a prerequisite (WRITE_ENABLED=true), but does not explicitly contrast with sibling tools like create_hr_case or close_hr_case. It lacks clear when-to-use vs alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the 'AI-powered' and 'semantic' aspects, which hint at non-deterministic or relevance-based behavior, but does not disclose other traits such as result formatting, pagination, or potential latency. The added context is minimal but not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the main action and scope. No filler or redundant information, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with only 3 parameters and no output schema, the description is sufficiently complete to understand its purpose and scope. It does not mention return format or pagination, but the lack of output schema makes some additional detail desirable, though not critical for a search operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameter descriptions present, so the schema already documents the parameters. The description does not add additional parameter semantics beyond what the schema provides, maintaining the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (search) and the specific resource set (KB, catalog, incidents), which distinguishes it from sibling tools like search_knowledge or search_catalog that target a single source. It is a specific verb+resource combination with no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for cross-source semantic search but does not explicitly state when to use it over alternatives or when not to use it. There is no mention of exclusions or alternative tool comparisons, so the guidance is limited to the implied scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and open-world behavior, so the bar is lower. The description adds the three analysis dimensions but does not disclose output format, whether all dimensions are always calculated, or how 'stale' is defined beyond the parameter hint. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence effectively front-loads the verb, target resource, and key dimensions. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema and read-only annotations, the description is largely sufficient for tool selection. However, it does not describe the return value or output structure, which would be helpful since no output schema is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all three parameters described, so the baseline is 3. The description adds meaningful framing by linking completeness and stale records to the parameters, but it does not provide extra syntax, defaults, or examples beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool analyses data quality for a table and lists the three concrete dimensions: completeness, duplicates, stale records. This distinguishes it from sibling tools such as check_table_completeness or get_table_record_count.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when an overall data quality assessment is needed, but it does not explicitly state when not to use this tool or mention alternatives like check_table_completeness for completeness-only checks. There is no exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a read-only, potentially incomplete operation. The description adds that it returns percentages per field, which is useful context. However, it does not disclose behavioral details such as sampling methodology, impact of sample_size, or limitations like openWorldHint implying results may not cover all records.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the primary action and output. It earns its place with no redundancy, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description provides essential return information (percentage of non-empty values per field). It mentions the input type (ServiceNow table) and the analysis focus. However, it omits potential edge-case behavior or calculation details (e.g., how empty strings are treated), which would be valuable for full completeness. Still, it is sufficiently complete for a read-only analysis tool with strong schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already documented. The description does not add additional meaning beyond the schema; it does not explain how 'sample_size' or 'query' affect the analysis results. Baseline 3 is appropriate when the schema carries the full parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Analyze data quality and field completeness for a ServiceNow table — returns percentage of non-empty values per field'. It uses specific verbs ('Analyze', 'returns') and identifies the resource ('ServiceNow table'), distinguishing it from siblings like analyze_data_quality, get_table_record_count, and query_records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for data quality analysis, but does not explicitly state when to use this tool versus alternatives. No mention of exclusions or comparison with other analysis tools like analyze_data_quality or query_records. Usage is implied by the purpose, but lacks direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior, so the description does not need to restate that. It adds the operational requirement 'requires WRITE_ENABLED=true', which is useful context beyond annotations. However, it does not disclose other behavioral details such as state transitions or irreversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the action and resource, includes the key requirement, and has no wasted words. It communicates the essential information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with full annotations and complete parameter schema, the description covers the core action and a prerequisite. It lacks output schema or error handling details, but for a straightforward close operation, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (sys_id, close_code, close_notes) already described. The description merely mentions close code and notes without adding new detail, so it does not add significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Close' targeting the 'change request' resource, with close code and notes as key parameters. This clearly distinguishes it from sibling tools like close_incident, close_hr_case, and update_change_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for closing change requests and mentions a prerequisite (WRITE_ENABLED=true), but does not explicitly contrast with alternatives like update_change_request or state when closing is appropriate. The guidance is present but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false). The description adds the WRITE_ENABLED=true prerequisite, which is useful operational context, but doesn't elaborate on irreversibility, side effects (despite openWorldHint=true), or return behavior. No contradiction with annotations, but limited additional behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence: 'Close an HR case with resolution notes (requires WRITE_ENABLED=true).' It conveys the verb, resource, input, and a critical prerequisite with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with rich annotations (destructiveHint, readOnlyHint, idempotency, openWorld) and full schema coverage, the description and annotations together provide a solid operational picture. The WRITE_ENABLED prerequisite is a valuable addition. The only omission is return value/confirmation behavior, which is minor given the simple close action and lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (sys_id, close_code, close_notes) already documented. The description's 'with resolution notes' merely reiterates the close_notes parameter without adding format, examples, or constraints. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Close' with the explicit resource 'HR case', clearly distinguishing it from sibling tools like close_incident, close_change_request, and update_hr_case. The 'with resolution notes' phrase adds meaningful specificity about the tool's primary function, making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for closing HR cases with resolution notes, but provides no explicit guidance on when not to use it or which alternatives apply (e.g., update_hr_case for non-closing modifications, close_csm_case for CSM cases). An agent relies primarily on the tool name and sibling context rather than explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, which cover the safety profile. The description adds the 'still operational' filter and the time-based condition, but does not disclose return format, pagination behavior, or interpretation of 'operational.' With annotations present, this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that front-loads the verb and resource, then clarifies the condition. Every word earns its place; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only query tool with well-documented optional parameters and no output schema, the description covers the core functionality. It could benefit from addressing what 'operational' means or how results are ordered, but overall it is sufficient for a simple find operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%—all three parameters (limit, ci_class, days_threshold) have descriptions, so the schema does the heavy lifting. The description adds marginal value by implying the days_threshold concept, but does not enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Find') and resource ('CIs') with a clear condition ('not updated within a given number of days that are still operational'). It distinguishes itself from sibling tools like cmdb_find_duplicates and cmdb_find_orphans by targeting stale but operational configuration items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied through the description—'find CIs not updated...' suggests when to use it, but there is no explicit guidance on when not to use it or how it compares to alternatives like cmdb_find_duplicates or cmdb_reconcile. No exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the WRITE_ENABLED=true prerequisite, which is beyond what the annotations state, but it does not disclose side effects, irreversibility, or what happens after completion. Annotations already signal readOnlyHint=false and idempotentHint=false, so the added behavioral context is minimal yet not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and prerequisite with zero unnecessary words. It is appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutating task with one required parameter and good annotations, the description covers the purpose and the key prerequisite. It does not explain return values or error conditions, but the schema and annotations fill most gaps, making this adequate for tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for sys_id and close_notes, so the schema carries the parameter semantics. The tool description adds no additional meaning about how these parameters should be used or formatted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Mark' with the resource 'task' and the action 'complete', clearly distinguishing it from generic tools like update_task or close_incident. The scope is unambiguous: it marks a task as complete. This is a precise and non-tautological purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the prerequisite WRITE_ENABLED=true, which gives some context for when the tool can be used. However, it does not explain when to use this tool versus alternatives such as update_task or close_incident, nor does it mention any exclusion scenarios. The context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), non-idempotent, non-destructive, and open-world. The description adds the NOW_ASSIST_ENABLED and WRITE_ENABLED requirements, which are useful environmental constraints not in annotations. However, it does not disclose side effects of creation (e.g., whether the workflow is immediately active, or if any related resources are changed) beyond the basic creation itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the primary action ('Create an agentic workflow linked to an AI agent') and appends the requirement in parentheses. It is concise, clear, and contains no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain what the response contains (e.g., the created workflow's sys_id), but it does not. The tool creates a potentially complex structure (steps array) without explaining how the workflow will be used or what happens after creation. The description is too sparse for a creation tool with these parameters and no schema-defined return.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 5 parameters, so the baseline is 3. The description adds no additional meaning about parameter relationships (e.g., how steps relate to the agent, or that agent_sys_id must reference an existing agent). The schema descriptions are minimal, but coverage is complete, so a baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and a specific resource ('agentic workflow linked to an AI agent'), clearly stating what the tool does. It distinguishes this from sibling tools like 'create_ai_agent' (creates the agent itself) and 'create_flow' (regular flow) by specifying the workflow is agentic and linked to an AI agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states prerequisites: 'requires NOW_ASSIST_ENABLED + WRITE_ENABLED', which provides clear conditions for when to use the tool. It also implies the need for an existing AI agent (since the workflow is 'linked to an AI agent'), but it does not mention alternatives like 'create_flow' for non-agentic workflows. Thus it gives clear context but lacks explicit exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not contradict annotations (readOnlyHint=false aligns with the create action). It adds one useful behavioral detail: the requirement WRITE_ENABLED=true, which is beyond the annotations. However, it does not disclose return values, failure modes, or side effects beyond the act 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It front-loads the main purpose and then adds a crucial prerequisite, making every word count.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the full schema coverage and annotations, the description is mostly sufficient. It identifies the target table and a configuration prerequisite, but it omits what the tool returns (e.g., the created project record) and does not address possible error conditions. This is a minor gap for an agent invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters have schema descriptions, so the baseline is 3. The description adds only the context that these parameters belong to the pm_project table, but it does not elaborate on how to structure the nested 'fields' object or the allowed values. The schema carries most of the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a PPM project (pm_project)' with a specific verb and resource, and the parenthetical 'pm_project' identifies the underlying table. This naturally distinguishes it from sibling tools like update_project or list_projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for creating new PPM projects, but it does not explicitly contrast with update_project or list_projects, nor does it provide guidance on when not to use it. The only explicit requirement is WRITE_ENABLED=true, which is more of a precondition than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) and non-destructive behavior (destructiveHint=false). The description adds the WRITE_ENABLED requirement and the specific table name, but doesn't disclose failure modes (e.g., duplicate dependencies, cycles) or what happens on success. This adds some context but doesn't go beyond the annotations significantly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and includes the key requirement. There is zero filler, and every word contributes meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple M2M link operation with full schema coverage and annotations for write/intent, the description is sufficient. It could mention return values or duplicate handling, but these aren't critical for the agent to select and invoke the tool correctly. The missing details are minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters completely with detailed descriptions explaining the direction (story is the blocked one, dependent_story is the blocker). Since schema coverage is 100%, the description adds no extra parameter meaning, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Link one agile story as dependent on another' and identifies the underlying M2M table (m2m_story_dependencies). This specific verb+resource phrasing distinguishes it from sibling tools like list_story_dependencies and delete_story_dependency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an operational prerequisite (Requires WRITE_ENABLED=true) but does not explicitly discuss when to use this tool versus alternatives. The use case is implied by the name and description, but there's no explicit guidance about exclusions or comparisons with list/delete dependency tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds the output format (JSON object) and the notion of 'matching a query,' but does not disclose additional behavioral aspects like pagination, limits, or whether the JSON is wrapped in a response envelope. It adds some value beyond annotations but not rich context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single sentence that front-loads the verb and resource, states the output format, and adds a purposeful hint about snapshots. Every word earns its place, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two optional parameters, read-only annotations, no output schema), the description covers the core purpose, the output form, and a practical use case. It does not detail the query encoding, but the schema already labels it as 'Encoded query filter,' so the description need not repeat that. It is sufficiently complete 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both parameters (query, category) have descriptive text. The description's phrase 'matching a query' loosely echoes the query parameter but adds no new semantics beyond what the schema already provides. Per the baseline, a score of 3 is appropriate when the schema carries the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Export'), identifies the resource ('system properties'), and specifies the output format ('JSON object'). It also adds a use case ('environment snapshots') that distinguishes it from sibling tools like list_system_properties, search_system_properties, or get_system_property, which have different output forms or purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for when to use this tool ('useful for environment snapshots') but does not explicitly state when not to use it or how it compares to alternatives such as search_system_properties or bulk_get_properties. It implies a use case but leaves the selection reasoning to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds no further behavioral details (e.g., permissions, response size, rate limits). It aligns with the read-only annotation, and there is no contradiction, but the description is minimal in extra behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately conveys the action and object. The '[Scripting]' tag is a minor addition but does not add unnecessary bulk. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with one parameter and no output schema. The description adequately indicates the return type (XML payload) and the migration context. While it could mention prerequisites or confirm the exact format, it is largely complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter sys_id as 'Update Set sys_id', and the description does not add any further meaning beyond that. With 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the XML export payload for an Update Set, which is a specific and distinct purpose. The verb 'Get' is precise, and the resource is well-defined, setting it apart from sibling tools like list_update_sets or preview_update_set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the use case 'as used in migration', which implies when it might be appropriate. However, it does not explicitly contrast with alternatives like preview_update_set or list_update_sets, so there is no clear exclusionary guidance. The usage context is implied rather than detailed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint and openWorldHint annotations already indicating a safe, read-only operation, the description adds the useful detail that related ACLs are included. However, it does not disclose any further behavioral aspects such as authentication requirements, response size, or whether ACLs are embedded or separate, so the added transparency is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no redundant words. It front-loads the verb and resource immediately, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 one parameter and no output schema, the description adequately conveys what will be returned (definition + ACLs). It does not explain return formats or edge cases, but the tool's simplicity and annotations make this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single sys_id parameter with a clear description ('System ID of the AI agent'), achieving 100% schema description coverage. The description adds nothing beyond this, so it does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and clearly identifies the resource as 'an AI agent definition and its related ACLs'. This distinguishes it from sibling tools like list_ai_agents and create_ai_agent, 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single AI agent by sys_id, but it does not explicitly state when to use this tool versus alternatives. There is no mention of list_ai_agents for listing or any exclusions, leaving the context to be inferred from the tool name and sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and openWorldHint, and the description is consistent with these (a read operation). It adds context by specifying the data scope (financial and lifecycle data), but doesn't go further to explain potential errors, permissions, or response format. The added context is minimal but non-contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that clearly states the tool's purpose and scope without unnecessary words or repetition. It is concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read operation with readOnlyHint and openWorldHint annotations, the description provides sufficient context. It specifies that the tool returns 'full details' and highlights financial and lifecycle data, making the behavior clear enough 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the only parameter (sys_id, 'Asset sys_id') with 100% coverage. The description adds no additional meaning to the parameter itself; it only elaborates on the output scope. This matches the baseline of 3 for complete schema coverage with no extra parameter info in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details of an IT asset, specifically including financial and lifecycle data. It distinguishes itself from list_assets (which lists assets) and track_asset_lifecycle (which likely tracks lifecycle processes), making it obvious this is for fetching detailed data about a single asset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving detailed asset information, but it does not explicitly state when to use it versus alternatives like list_assets or update_asset. No exclusions or alternative comparisons are provided, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds value by specifying the returned fields (name, account, phone, email), which is useful given there is no output schema, but it does not disclose behaviors such as match semantics or not-found handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the tool's purpose and return scope without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, single-parameter read tool with rich annotations and full schema coverage, the description is adequately complete. It covers the purpose, resource, and expected output fields, though it could optionally mention the sibling list tool or failure behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—the parameter `name_or_sysid` is already documented as accepting contact name, email, or sys_id. The description adds nothing beyond the schema for parameter meaning, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') with a clearly defined resource ('customer contact') and enumerates the returned details (name, account, phone, email). It distinguishes itself from siblings like list_csm_contacts (list vs. single record) and get_csm_account (different entity).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the 'get' pattern and the existence of sibling tools like list_csm_contacts, suggesting this is for fetching a single contact's details by identifier. However, no explicit guidance is given about when to prefer this tool over alternatives or what prerequisites exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers safety. The description adds that the result includes body and headers, which is useful behavioral context. However, it does not disclose pagination, error behavior, or any rate limits, so the added transparency is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that front-loads the purpose and key content ('including body and headers'). No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only getter with no output schema, the description is adequate: it states what is returned. It doesn't cover edge cases or return field details, but given the tool's simple nature and annotations, it's complete enough. Could have added a pointer to list_email_logs for sys_id discovery.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the only parameter (sys_id) fully, so the description's contribution is minimal. It doesn't explain how sys_id is used or where to find it, but the baseline of 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get'), identifies the exact resource ('email log entry'), and specifies the scope ('full details including body and headers'). This clearly distinguishes it from list_email_logs and other get_* tools that retrieve metadata or summaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies using this tool when full details of a single email log entry are needed, but it does not explicitly state when not to use it or mention alternatives like list_email_logs to obtain the sys_id. It gives no exclusions or comparison with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating safe read-only behavior. The description adds value by specifying that the response includes actions and trigger, giving the agent an idea of what to expect. However, it does not disclose any edge cases, permission requirements, or nuances 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the verb and resource. It avoids redundancy and is highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, read-only hints), the description is fairly complete. It explains what will be returned (full details, actions, trigger) and is sufficient for an agent to understand the tool's purpose. It could mention return format, but the 'full details' phrase covers the essentials.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameter description (name_or_sysid with a clear explanation). The tool description does not add anything beyond the schema, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details of a Flow Designer flow, explicitly mentioning actions and trigger. This distinguishes it from sibling tools like list_flows (which lists flows) and get_flow_execution (which focuses on execution details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need complete configuration details of a specific flow, but it does not explicitly state alternatives or when not to use it. There is no mention of list_flows or get_flow_execution as alternatives, so usage guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds minimal detail about the content (full activity log and journal entries) but does not disclose behavioral traits such as pagination, ordering, or access requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 11 words, front-loaded with the primary action and resource. It contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 parameter and no output schema, the description sufficiently communicates the high-level return content (activity log and journal entries). It could be more detailed about output structure, but it is adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter hr_case_sysid already described as 'sys_id of the HR case'. The tool description does not add further semantics beyond what the schema provides, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the full activity log and journal entries for an HR case, using a specific verb and resource. It distinguishes itself from sibling tools like get_hr_case (which retrieves case details) and list_hr_cases (which lists cases).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when one needs activity history for an HR case, but it does not explicitly state when to use this tool over alternatives or mention any exclusions. No direct comparison to siblings like get_hr_case is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds the type of data returned but does not discuss edge cases, error behavior, or required permissions. It is consistent 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that front-loads the verb and resource while using parentheses for clarifying detail. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 fully documented parameter and clear annotations, the description adequately conveys the purpose and content of the response. It could be slightly richer about return format, but given the simplicity and annotations, it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter user_identifier is fully documented in the schema with its description 'Username, email, or sys_id of the user', providing 100% coverage. The tool description does not add additional parameter context beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves an HR profile for a user, specifying the content areas (employment details, department, manager). This distinguishes it from sibling tools like get_user (basic user info) and update_hr_profile (which modifies HR profile).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly say when to use this tool instead of alternatives. It implies via the parenthetical that this is for HR-specific profile data, but lacks explicit exclusions or comparisons to siblings like get_user or get_hr_case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds that the response includes tasks and SLAs, but does not disclose behaviors like exact-name matching limitations, error handling, or response envelope. This is acceptable given the read-only annotation but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and key included content without any filler. Every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only lookup, the description adequately covers purpose and expected content (tasks and SLAs). It could mention exact-name matching or explicitly differentiate from list_hr_services, but the tool's simplicity and the readOnlyHint annotation make it sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter sys_id_or_name already explains it accepts a sys_id or exact name. The description adds no additional parameter semantics beyond restating that it targets a specific service, so the schema carries the full burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and identifies the resource ('specific HR service') along with the included content ('tasks and SLAs'). It clearly differentiates from siblings like list_hr_services by targeting a single service lookup rather than a list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'specific HR service' implies this is for single-item lookup by sys_id_or_name, but there is no explicit guidance on when to use this tool versus alternatives like list_hr_services. Usage context is implied but not fully articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 covered. The description adds that it returns row count and transform status, which is useful context but does not disclose any additional behavioral traits like error handling or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that is front-loaded with the action and resource. Every word earns its place, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-sys_id tool, the description plus annotations and schema provide enough context. It states what the response will include (row count, transform status), which covers the most important expectations. It doesn't explain edge cases, but the tool's simplicity makes this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description ('Import Set sys_id') is clear. The description adds minimal extra meaning beyond saying 'specific Import Set', but the schema already 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('Import Set'), clarifies the scope ('specific'), and mentions key contents ('row count and transform status'). It clearly distinguishes from the sibling list_import_sets, which is a list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by sys_id, but does not explicitly state when to use this versus list_import_sets or other alternatives. No exclusions or conditions are provided, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds little beyond stating 'full details' without specifying what that includes (e.g., work notes, attachments) or any response format. No additional behavioral traits like permissions, rate limits, or side effects are disclosed, so the description does not add significant value over annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the purpose and includes the parameter options. No redundant or filler content; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter get tool with good annotations and no output schema, the description is adequate. It tells the agent how to identify the incident and that full details are returned. However, 'full details' is slightly ambiguous regarding scope (e.g., does it include work notes, attachments?), so it is not a perfect 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear parameter description, but the description enhances it with a concrete example 'INC0012345' which clarifies the expected format. This adds practical meaning beyond the schema's description, earning a score above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get full details of an incident' with a specific verb and resource, and distinguishes from siblings by specifying identification via number or sys_id. It is immediately clear this is the reference lookup tool for incidents, distinct from create_incident, update_incident, and generic get_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this to retrieve full incident details when you have an incident number or sys_id. However, it does not explicitly mention when not to use it or provide alternative tools such as query_records or get_record. Context is present, but exclusions and alternates are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so the tool is known to be a read operation. The description adds context by specifying that 'template and conditions' are included in the returned details, which provides some behavioral clarity. However, it does not disclose other traits like permissions, rate limits, or the exact response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It efficiently conveys the tool's purpose and key return contents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with one parameter and good schema/annotations, the description is nearly complete. It specifies that full details including template and conditions are returned. Minor gap: it doesn't clarify whether 'full details' includes all fields or just those highlighted, but this is not critical given the annotations and simple scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the only parameter (sys_id_or_name) with a clear description: 'Notification sys_id or name'. The tool description adds little beyond the schema, but since schema coverage is 100%, the baseline of 3 is appropriate. No additional parameter meaning is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 full details of an email notification definition including template and conditions'. It uses a specific verb ('Get'), identifies the resource ('email notification definition'), and lists included components, distinguishing it from sibling tools like list_notifications, create_notification, and update_notification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single notification's details by sys_id or name, but provides no explicit guidance on when to use this tool versus alternatives such as list_notifications. There is no mention of exclusion criteria or preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is established. The description adds the concept of 'historical time-series' which is useful context, but does not disclose output format, pagination, or any operational constraints beyond what annotations and schema already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that front-loads the verb and resource. No wasted words; the statement earns its place by conveying both the action and the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With simple parameters, annotations, and no output schema, the description is adequate for selection and invocation. It could be improved by specifying the output shape or units, but the provided information is sufficient for basic use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter (indicator_sys_id, start_date, end_date, limit) is already described. The description adds no additional meaning about parameter relationships or format, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('historical time-series data for a PA indicator'), and the purpose ('to identify trends'). It distinguishes from sibling tools like get_pa_indicator (which likely returns indicator metadata) and list_pa_indicators (which lists indicators).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for trend analysis via 'to identify trends', but does not explicitly compare to alternatives such as trend_query or visualize_trend. It provides no exclusions or when-not-to-use guidance, so it only partially guides tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds minimal extra context about the scope (full configuration details) and identifier flexibility, but does not disclose potential response size, error conditions, or any other behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the verb and resource, includes the key parameter detail, and contains no redundant words or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with one well-documented parameter and no output schema, the description is adequate. It tells the agent what the tool does and how the parameter works. However, it does not detail the response structure or content of 'full configuration details', which could be ambiguous, but given the simplicity and annotations, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the input schema's property description fully explains that 'id' accepts a sys_id or url_suffix with examples. The tool description repeats this information without adding new semantic detail, so it does not enhance what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'full configuration details of a Service Portal', with a specific method 'by sys_id or URL suffix'. This distinguishes it from siblings like list_portals (listing) and get_portal_page (page-level details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use this tool when you need full configuration details for a specific portal identified by sys_id or URL suffix. However, it does not explicitly differentiate from alternatives like list_portals for enumerating portals or get_portal_page for a specific page, nor does it state prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds that it returns full details including CSS variables, but does not disclose behavior for missing sys_ids or any permission requirements. Minimal added context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise single sentence of 14 words, front-loaded with the verb and resource, and contains no redundancy or irrelevant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 one required parameter and strong annotations, the description is adequate. It conveys the purpose and a key aspect of the return content (CSS variables). No output schema exists, but the tool's simplicity keeps the description sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter sys_id ('Theme sys_id'). The description does not add any additional meaning or context about the parameter, meeting the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and identifies the resource as 'Service Portal theme'. Adding 'full details including CSS variables' clarifies the scope and distinguishes it from list_portal_themes and other getter tools, which is strong purpose clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the tool is for retrieving a specific theme by sys_id, but it neither explicitly names alternatives nor states when to use this versus list_portal_themes. The context is implied rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the read-only safety is known. The description adds 'full details' but no further behavioral context such as return format, permissions, or error behavior. It is not contradictory, but adds minimal value 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence, front-loaded with the verb and resource, with no filler or repeated information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a low-complexity read-only tool with one well-documented parameter and readOnly annotations. 'Full details' signals the return scope, and while there is no output schema, the description is sufficient for a simple lookup use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the parameter description already states 'Problem number (PRB...) or sys_id'. The tool description essentially repeats this, adding no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb 'Get' and resource 'problem', with clear scoping 'by number (PRB...) or sys_id'. It distinguishes from siblings like create_problem, update_problem, and resolve_problem.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need a problem's full details by identifier, but it lacks explicit guidance about when to use alternatives or when not to use this tool. The sibling list provides context but no direct exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the read-only nature is covered. The description does not add extra behavioral context such as permissions, side effects, or return format, but it is consistent with the annotation. No contradiction exists, and the annotation lowers the bar for additional disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential purpose without any redundant words. It is concise and clear, earning the maximum score for structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple get tool with one parameter, no output schema, and read-only annotations. The description is adequate for the intended use: retrieving details of a specific playbook/process. While it does not enumerate what 'details' includes, the tool's simplicity and the read-only annotation make this a minor gap. Overall, it is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the single parameter name_or_sysid with a clear description ('Playbook or process name or sys_id'). Schema coverage is 100%, so the baseline of 3 applies. The tool description adds no further parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get details') and the specific resource ('Process Automation Designer playbook or process'), making it easy to distinguish from siblings like list_process_automations which lists items rather than retrieving one. The verb 'get' plus the concrete resource leaves no ambiguity about 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: to retrieve details for a single playbook/process. However, it does not explicitly state when to use this tool over alternatives such as list_process_automations, nor does it mention any prerequisites or exclusions. This is sufficient for a simple get tool but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and openWorldHint annotations cover the safety profile. The description adds some context about the returned data ('full configuration including endpoints') but does not disclose other behavioral traits like error handling, authentication requirements, or response format beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence (12 words) that is front-loaded with the verb and contains no fluff. Every word contributes to clarifying the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 parameter and no output schema, the description adequately conveys the scope ('full configuration including endpoints'). It could be slightly more detailed about what fields are returned, but given the simplicity, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter (sys_id_or_name) with a clear description. The tool description does not add additional semantic meaning beyond what the schema already provides, matching the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('full configuration of an outbound REST Message'), and adds detail about including endpoints. This distinguishes it from sibling tools like list_rest_messages or create_rest_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (fetch a single REST message's full config) but does not explicitly contrast with alternatives or state when to use it vs. list_rest_messages. No exclusions or alternate tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description's 'Get full details' is consistent with these. However, the description adds no extra behavioral context beyond the basic purpose, such as response size, field set, or potential limitations, making it adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose. Every word contributes value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with one well-documented parameter, the description is largely sufficient. However, 'full details' is vague and there is no output schema, so an agent cannot know exactly which fields will be returned; still, the tool's simplicity and clear parameter reduce the need for more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema's sole parameter 'id' already has a clear description ('App sys_id or scope name (e.g. "x_myco_myapp")'). The tool description repeats this information without adding further detail, so it meets the baseline for high schema coverage without augmenting it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a scoped application's full details using either a sys_id or scope name. This specific verb+resource+lookup-method combination distinguishes it from siblings like list_scoped_apps, create_scoped_app, and update_scoped_app.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives, such as list_scoped_apps for discovery. The need for an identifier (sys_id or scope name) is implied, but the description does not contrast with sibling tools or state exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's main added value is the requirement of SCRIPTING_ENABLED=true. It does not elaborate on response format, error behavior, or any side effects, but with annotations covering the safety profile, this is acceptable but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the main purpose and quickly adds the key prerequisite. No wasted words; all information is essential and clearly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter get tool, the description covers the purpose and the critical prerequisite. The output (full script body) is implied, and the schema documents the parameter. It is nearly complete, though it could mention handling of invalid IDs or exact return format, but this is not essential for a tool of this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'sys_id_or_name' described as 'Script include sys_id or api_name'. The tool description adds no additional meaning or nuance about the parameter, so it relies on the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Get), the resource (script include), and the specific outcome (full script body). It distinguishes from sibling tools like list_script_includes and create_script_include by emphasizing the retrieval of the complete script source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite (SCRIPTING_ENABLED=true) which gives context for when the tool can be used, but it does not explicitly state when to prefer this over alternatives, nor does it mention any exclusions or alternative tools. Usage is implied rather than fully guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 that the tool returns inputs, outputs, and actions, but does not disclose any additional behavioral traits (pagination, authentication, or edge cases). This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise, front-loaded sentence: 'Get full details of a subflow including its inputs, outputs, and actions.' Every word adds value with no repetition of schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 well-documented parameter, no output schema, and readOnlyHint/openWorldHint annotations, the description covers the essential purpose and return content. It could mention uniqueness constraints or error handling, but these are not critical for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter (name_or_sysid) with 100% coverage. The description does not add further meaning beyond what the schema provides, such as how names are resolved versus sys_ids.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get'), the resource ('subflow'), and the specific scope ('full details including inputs, outputs, and actions'). This distinguishes it from sibling tools like list_subflows, which lists subflows without full details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like list_subflows. The verb 'Get' implies retrieval of a specific subflow's details, but there is no stated exclusion for cases where only a summary is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only (readOnlyHint: true), and the description's 'Get details' is consistent. However, the description adds no extra behavioral context beyond what annotations provide, such as whether all task subtypes are included or behavior when nothing is found. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to meaning, making it highly concise and appropriately structured for a simple getter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one well-documented parameter and strong annotations, the description fully covers the core use case. It lacks an output schema but 'details' reasonably implies returning the record's fields. The absence of more explicit return-value explanation is acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter, describing it as 'Task number or sys_id'. The tool description repeats this same information ('by number or sys_id') without adding new semantics like format, validation rules, or edge cases. The schema alone is sufficient, so the description adds no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb 'Get' and resource 'task record' with the identifying field 'number or sys_id'. It clearly states the tool's scope as 'any task record', distinguishing it from siblings like get_incident or get_change_request that target specific task subtypes. The purpose is unambiguous and not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies broad applicability ('any task record') but does not explicitly state when to choose this over more specific getters like get_incident or get_problem. There are no stated exclusions or alternative tool references, leaving the decision to the agent without concrete guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. It adds 'including its field mappings' as a return-content detail, but does not disclose potential edge cases, permissions, or output structure. This is adequate given the read-only nature, but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence delivers all essential information. Every word earns its place, with no fluff or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It's a simple read-only getter with one parameter and no output schema. The description covers what it returns at a high level ('details...including its field mappings'). Given the tool's simplicity, this is mostly complete, though a bit more detail on the response structure would be useful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of the parameter, explicitly stating 'Transform Map sys_id or name'. The tool description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('Transform Map'), and even specifies the scope ('including its field mappings'). It clearly distinguishes from sibling tools like list_transform_maps (list) and run_transform_map (execute), 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving details of a single Transform Map when you have its sys_id or name, but it does not explicitly mention when to use it versus alternatives like list_transform_maps or list_transform_field_maps. No exclusions or direct alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and openWorldHint, setting a low bar. The description adds that details include 'tabs and lists', which is useful content context, but it does not disclose other behavioral aspects like error handling or permission requirements. It adds some value beyond annotations but is not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a clear verb-object structure, no fluff, and front-loaded content. Every word earns its place, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple get-by-sys_id tool with one parameter, good annotations, and no output schema. The description adequately conveys the main purpose and content scope ('tabs and lists'), which is sufficient for a getter. It could mention error cases but is not necessary for basic completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters, and the description adds no extra meaning for sys_id beyond the schema's 'Workspace sys_id'. The baseline of 3 applies because the schema does the heavy lifting; the description does not compensate or add detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'workspace', and clarifies it includes 'tabs and lists', distinguishing it from siblings like list_workspaces (which lists) and create_workspace. This is a precise and informative purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving details of a single workspace by sys_id, but it does not explicitly state when to use this versus alternatives like list_workspaces or configure_workspace_list. There is no mention of exclusions or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds no further behavioral context such as pagination behavior, ordering, or whether all agents (including archived) are returned. With annotations, this is adequate but lacks additional useful detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single succinct sentence ('List AI agent definitions') that conveys the core purpose with zero wasted words. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low tool complexity, full schema coverage, and annotations that signal safe read-only behavior, the description is almost complete. It lacks explicit mention of what the response contains, but the phrase 'AI agent definitions' implies a list of definitions. Minor gap: no mention of default pagination or scope (e.g., includes inactive agents), but these are covered by the schema parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'limit' and 'active' fully documented in the input schema. The description adds no extra parameter context, but the baseline of 3 applies because the schema already handles parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('AI agent definitions'), clearly distinguishing it from sibling tools like get_ai_agent (singular retrieval) and create_ai_agent (creation). It unambiguously states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when wanting to list all AI agent definitions, but provides no explicit guidance on when to choose this tool over alternatives like get_ai_agent or create_ai_agent. No exclusions or alternative recommendations are mentioned, leaving the context to be inferred from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 little beyond 'optionally filtered by suite', which is more of a parameter detail than a behavioral disclosure. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, front-loaded with the action and resource, and no wasted words. The optional filter is mentioned directly and succinctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with read-only annotations and 100% schema coverage, the description is adequate. It does not explain return format or pagination, but the absence of an output schema and the simple nature of listing make this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters (limit, active, suite_sys_id) are already documented in the schema. The description only mentions optional suite filtering, adding no meaningful semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'ATF test cases', with an optional filter by suite. This distinguishes it from siblings like list_atf_test_results (results vs cases) and get_atf_test (single item vs list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need a list of ATF test cases, optionally filtered by suite) but does not explicitly mention alternatives or exclusions, such as using get_atf_test for a single test or list_atf_test_results for results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds minimal context ('used by integrations') but does not disclose behaviors like pagination, sorting, or result size limits beyond what the schema parameters imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that states the tool's purpose with no unnecessary words. It is front-loaded and immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with well-documented optional parameters and no output schema, the description is adequately complete. It could mention default limit or filtering behavior, but these are already captured in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions, so schema coverage is 100%. The tool description provides no additional parameter meaning, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'List' and specifies the resource as 'connection and credential aliases used by integrations', making the tool's purpose explicit and distinct from other list tools. It clearly identifies what is being listed and for what context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives, but the purpose is self-evident for listing credential aliases. There are no obvious sibling tools with the same function, so the description implies usage without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's read-only nature aligns without contradiction. The description adds the specific scope of what is listed (file/JDBC/REST loaders), but does not disclose additional behavioral traits such as pagination defaults, return structure, or whether sensitive fields like passwords are excluded. The annotations cover the safety profile, so a baseline score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core purpose and scope directly. There is no wasted wording, and the parenthetical clarifies the loader types efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with a clear schema and read-only annotations, the description is nearly complete. It clearly identifies the resource and scope, though it could have briefly mentioned that it returns definitions (metadata) rather than the actual import data, and it does not guide usage relative to sibling list_import_sets. These are minor gaps given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of the three parameters (type, limit, query) with descriptions, so the description need not add param-level detail. The baseline of 3 applies because the schema carries the semantic burden and the description adds no further parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clear resource ('Import Set data source definitions'), while clarifying the scope ('file/JDBC/REST loaders'). This distinguishes it from the sibling tool 'list_import_sets', which likely lists import sets themselves rather than their source definitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by naming the resource type and loader categories, but it does not explicitly state when to use this tool versus alternatives like 'list_import_sets' or 'get_import_set'. There is no exclusion guidance, making the usage cues 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the readOnlyHint and openWorldHint annotations (listing is read-only, open-world). However, it does not add behavioral context beyond what the annotations already provide, such as pagination behavior or default filtering, which is acceptable given the annotations but not enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that directly conveys the tool's purpose without any waste. It is front-loaded with the action and resource, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional parameters and annotations covering safety, the description is nearly complete. It lacks explicit guidance on alternatives or return format, but the schema and annotations cover the essential details, leaving only minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for both parameters (limit and active). The description does not add any additional meaning beyond the schema, so it meets the baseline but does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'DevOps pipeline configurations' and a scope 'registered in ServiceNow'. This clearly distinguishes it from siblings like get_devops_pipeline (single pipeline) and list_deployments (deployments, not configurations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use by naming the resource, but it does not explicitly state when to use this tool versus alternatives. There is no mention of when not to use it or how it compares to get_devops_pipeline or list_deployments, leaving the guidance 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.
Behavior3/5
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 that run status is included, which is useful behavioral context. However, it does not disclose default filtering, sorting, or pagination behavior beyond what the schema indicates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or redundancy. It communicates the core purpose and relevant output detail ('run status') efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description and schema provide sufficient context for basic invocation. It lacks explicit details on return fields beyond 'run status', but the simplicity of the tool reduces the need for more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the single 'active_only' parameter has a clear description). The tool description adds no additional parameter semantics, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists discovery schedules and includes their run status. This is a specific verb+resource combination that distinguishes it from siblings like 'run_discovery_scan' (which executes scans) or 'list_scheduled_jobs' (generic scheduled jobs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The name and description imply usage for viewing discovery schedules, but there is no explicit guidance on when to use this vs. alternatives like 'list_scheduled_jobs' or when to set the 'active_only' parameter. The 'when-to-use' is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description's 'list' action is consistent. No additional behavioral details (e.g., defaults, pagination) are provided, but the annotations 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that is front-loaded with the verb and resource. Every word adds value, with no unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 with two optional parameters and strong annotations, the description is adequate. It does not mention return fields, but that is not required given the simplicity and lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (limit and query) described. The tool description adds no extra meaning beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists registered event definitions from the ServiceNow event registry, using a specific verb and resource. It implicitly distinguishes from sibling tools like get_event_registry_entry, register_event, fire_event, and list_event_log.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for browsing/searching event definitions but provides no explicit when-to-use guidance or comparison to alternatives. Similar tools like list_event_log or get_event_registry_entry exist, but no exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description is consistent with a read-only operation. It adds nothing beyond the annotation about behavior (e.g., no mention of pagination, default limit, or result shape), which is acceptable given the low bar for simple list operations, but it doesn't enrich the behavioral context further.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the core purpose and lists filters efficiently. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 required parameters and full schema coverage, the description covers the essential functionality. It lacks an explicit note about return values (no output schema exists), but given the simplicity and the absence of complex behavior, it is adequately complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter described (limit, query, active, category). The description's mention of 'filter by name, category, or active status' restates the schema without adding new meaning or usage nuances, so it stays at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Flow Designer flows and optionally filters by name, category, or active status. It uses a specific verb ("List") and resource ("Flow Designer flows"), distinguishing it from sibling tools like get_flow or create_flow. The mention of filters adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the optional filters, but it does not explicitly state when to use this tool over alternatives like list_process_automations or get_flow. There is no exclusionary guidance, so it meets only the 'implied usage' level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 only the optional search filter, which is a functional detail rather than a behavioral disclosure. It does not mention pagination, result ordering, or output format. With annotations present, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words. It is front-loaded with the action and resource, and every word adds value. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the presence of annotations, and complete parameter descriptions, the description is sufficient. It could potentially clarify default behavior or output but is not incomplete for the intended use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'limit' and 'query' parameters fully described in the input schema. The description's mention of 'optional search filter' adds minimal value beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists groups, with an optional search filter. This distinguishes it from sibling tools like get_group (singular) and create_group/update_group. The verb 'list' plus resource 'groups' is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing groups, which is clear from context, but it does not explicitly mention when to use this versus alternatives (e.g., get_group for a single group). There is no explicit exclusion or alternative recommendation, so it only provides implied guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, covering safety and openness. The description adds the definition of 'homepage dashboards' as CMS content pages used as homepages, which is useful context, but does not discuss pagination, query behavior, or the implications of openWorldHint. It neither contradicts annotations nor adds substantial 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and clarifies the resource without any redundant words. It earns its place and wastes no space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with two optional parameters, the description plus schema is fairly complete. It defines the concept of 'homepage dashboards' which adds contextual meaning, though it could optionally mention return format or relation to other page types. Minor gap, but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both 'limit' and 'query'. The tool description does not add any parameter information beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List homepage dashboards (CMS content pages used as homepages)' clearly states the action and resource, and the parenthetical differentiates it from broader page-listing tools like list_portal_pages. The verb 'List' is specific and the scope is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a user needs homepage dashboards but provides no explicit context, alternatives, or exclusions. There is no mention of when to prefer this over list_portal_pages or other listing tools, leaving usage fully implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds no further behavioral context such as pagination, access control, or scope. It only restates the purpose, which is already clear from the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action and object, no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple list semantics, annotated read-only behavior, and fully documented parameters, the one-sentence description is sufficient. It doesn't need to explain return values since no output schema exists and the tool's behavior is straightforward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a description. The description's mention of 'status, subject person, service' merely renames existing parameters (state, subject_person, hr_service) without adding syntax or value details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'HR cases', and specifies optional filters. This distinguishes it from sibling tools like get_hr_case (single case) and list_hr_tasks (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a list of HR cases with optional filtering, but doesn't explicitly name alternatives or exclusions. It provides clear context that this is a listing tool with filter capabilities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds that it records success/failure states, which is useful context. However, it does not disclose output format, default ordering, or pagination behavior. Given the annotation coverage, this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler. It includes the essential purpose and a clarifying parenthetical about content, making it efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with read-only annotation and self-documenting parameters, the description provides adequate context. It explains the result is a run history log, and the absence of an output schema is not a major gap since this is a straightforward list operation. However, it lacks details on date range or result ordering, which would be nice but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (limit, status, job_sys_id) have descriptions in the input schema, covering 100% of the schema. The description does not add additional meaning to the parameters, so it relies fully on the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List recent run history for scheduled jobs (success/failure log)' uses a specific verb and resource, clearly distinguishing it from tools like list_scheduled_jobs which list the jobs themselves, and from execution log tools. The parenthetical clarifies the content type (success/failure log), which is helpful.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly communicates when to use the tool (for recent run history of scheduled jobs), but it does not explicitly state when not to use it or mention alternatives such as list_scheduled_jobs or get_scheduled_job. No exclusions or alternative use cases are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, which tell the agent this is a safe read with potentially incomplete results. The description adds small context (the sysevent_email_action table) but does not disclose additional behaviors like pagination, default limits, or how filters interact with openWorldHint. The bar is lowered due to annotations, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and resource without any filler. Every word earns its place, and the parenthetical table name is useful technical context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with 5 optional filter parameters, no required params, and good annotations, this description is mostly complete. It conveys the purpose and scope (email notification definitions). However, with no output schema, the agent must infer what fields are returned, and the description does not mention that results may be filtered or limited. Still, the openWorldHint annotation covers some of that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — all five parameters have descriptions in the schema. The tool description adds no parameter-specific meaning beyond the schema, so the baseline of 3 applies. It only mentions the table name, which is tangential to parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('email notification definitions') and provides the underlying table name (sysevent_email_action). This distinguishes it from sibling tools like get_notification (single record) and create/update_notification (mutations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for viewing all email notification definitions, but it does not explicitly state when to use it over alternatives such as get_notification, list_notification_subscriptions, or schedule_notification. No exclusions or alternative guidance is provided, leaving usage to be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the read-only nature is covered. The description adds the 'opted in/out' context, but does not disclose additional behavioral traits like pagination, default ordering, or that it returns only opt-in/opt-out statuses. It adds marginal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that clearly conveys the tool's purpose without any redundant wording. It earns its place with the clarifying parenthetical about opt-in/out status.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 with well-documented parameters and no output schema, the description is mostly sufficient. It could mention what the response contains (e.g., a list of subscription records) or how filters interact, but the core intent is clear and the schema covers the parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (limit, user_sys_id, notification_sys_id) have their own descriptions. The tool description does not add any parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('List user subscriptions to notifications') and clarifies the field's meaning ('who has opted in/out'). This clearly distinguishes it from sibling tools like list_notifications, which lists notification definitions rather than user subscription states.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for viewing notification subscription states but does not explicitly state when to use it over alternatives or mention exclusions. There are no references to list_notifications or related tools, so usage context is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 minimal behavioral context beyond stating it lists jobs and schedules; it does not mention default filters, pagination, or other behaviors that would be useful beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb 'List', and contains no redundant information. Every word adds value in clarifying the tool's scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with optional parameters and no output schema, the description sufficiently states the core function. It is slightly incomplete in not clarifying how this differs from generic scheduled job listings or providing guidance on filter defaults, but the schema and annotations fill most gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (limit, query, active) explained in the schema. The description adds no additional parameter meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and clearly identifies the resource as 'Performance Analytics data collection jobs' with their schedules. It distinguishes from sibling tools like list_pa_indicators and get_pa_job by specifying the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for listing PA jobs and schedules but provides no explicit guidance on when to use it versus alternatives such as get_pa_job or list_scheduled_jobs. There is no mention of exclusions or when to choose a different tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds the prerequisite that SCRIPTING_ENABLED must be true, which is useful context beyond the annotations. However, it does not describe expected return structure or potential errors, so the additional transparency is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core purpose and adds a necessary prerequisite. There is no filler or redundant content. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (a read-only list operation with optional filters), the combination of a clear description, complete parameter schema, and safety annotations covers most needed context. The prerequisite is disclosed. It could mention return format or pagination, but the limit parameter and default cover that reasonably. Overall, it is complete enough for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for all three parameters (limit, query, active), so the schema already defines their meaning. The description does not add any additional parameter semantics beyond what is already in the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('script includes'), making it obvious this is a listing operation. It also includes a prerequisite ('requires SCRIPTING_ENABLED=true') that adds context. This distinguishes it from siblings like get_script_include (which retrieves a single item) and create/update_script_include (writes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage ('List script includes') but does not explicitly mention alternatives or when to choose this over get_script_include or other list tools. The prerequisite 'requires SCRIPTING_ENABLED=true' is useful but does not clarify the decision between related tools. The usage is largely inferred from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is known. The description adds a useful output detail ('compliance status') which is behavioral since there is no output schema, but it does not disclose pagination, filtering behavior, or result size limits beyond what the schema already provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action, target, and key output field. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional parameters, full schema coverage, and readOnly/openWorld annotations, the description is adequate. It specifies the resource and key output attribute, and the schema handles the parameters. It could be more complete by differentiating from get_license_compliance, but that gap is largely covered by the purpose clarity dimension.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'limit' and 'query' described. The tool description itself adds no additional parameter semantics, but since the schema fully documents the parameters, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('software license records') and adds the scope 'with compliance status,' distinguishing it from related tools like get_license_compliance and list_assets. It clearly conveys that this tool returns a list of license records enriched with compliance status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case—when you need to list software licenses and their compliance status—but does not explicitly state when to prefer this tool over alternatives such as get_license_compliance or list_assets. No exclusions or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows it's a safe read operation. The description adds the filter options but doesn't disclose pagination behavior, return format, or any edge cases. With annotations covering the safety profile, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no redundant wording. It front-loads the verb and resource, then specifies optional filters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 with fully documented parameters, the description is sufficient. The lack of an output schema is not a gap here since the action is straightforward, and the annotation provides safety context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (limit, state, sprint) already described. The description's mention of 'optional sprint or state filter' reiterates the schema without adding new meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List), the resource (agile stories), and optional filters (sprint or state). It distinguishes this tool from sibling list tools like list_epics and list_scrum_tasks by explicitly naming 'agile stories'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the agent needs to retrieve stories with optional filters, but it provides no explicit guidance on when to prefer this tool over alternatives like list_epics or list_scrum_tasks, nor any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 that it lists mappings within a transform map but does not disclose additional behavioral details like pagination or response format. This matches the calibration baseline for a simple list operation 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the purpose without any extraneous words. It is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two parameters, one required, and no output schema, the description is adequate. It clearly states the action and target. It does not explain what 'field-level mappings' are, but that is domain knowledge. It could have added a note about pagination or sorting, but the schema covers the limit parameter, making it sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters are well-described in the schema ('Parent Transform Map sys_id' and 'Max records to return (default 50)'). The tool description adds no extra parameter semantics, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and a clear resource 'field-level mappings within a Transform Map'. It distinguishes this tool from siblings like list_transform_maps and get_transform_map by focusing on the field-level mappings within a specific transform map.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: you would call this when you need to see the field mappings inside a particular transform map. However, it does not explicitly mention alternatives or exclusions, so 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, covering safety aspects. The description adds context about scope (operational metrics) but does not disclose return format, limitations, or any behavioral details beyond what annotations imply. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-constructed sentence that front-loads the core action and provides illustrative examples. Every word earns its place with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with the detailed schema and annotations, is mostly sufficient for understanding and invoking the tool. However, it does not mention that a model must be trained first (given the sibling ml_train_anomaly_detector), which could be a relevant prerequisite. Return format is also unspecified, but the lack of an output schema and read-only nature mitigate this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with descriptions for all four parameters, including defaults and examples. The description adds no additional parameter semantics beyond naming metric types, so it does not exceed the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Run anomaly detection') and the resource ('operational metrics'), with concrete examples like alert volume and incident trends. It distinguishes well from siblings like ml_train_anomaly_detector, which is about training rather than running detection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives such as ml_train_anomaly_detector. The detection vs training context is implied but not stated, and there is no mention of prerequisites or when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, establishing that this is a write operation. The description adds the WRITE_ENABLED=true prerequisite, which is useful context, but it does not disclose what happens after rejection (e.g., irreversibility, notifications, status change).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It front-loads the action and resource, and includes the prerequisite inline without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with complete schema descriptions and annotations covering safety, the description provides sufficient context. It includes the WRITE_ENABLED prerequisite, which is a notable operational constraint. The lack of an output schema is not a gap since none exists, and the scope is limited to rejecting a pending request.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes both parameters (sys_id as 'System ID of the approval record' and comments as 'Reason for rejection'), and the description adds no further parameter-specific meaning. As schema coverage is 100%, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Reject') and resource ('pending approval request'), clearly distinguishing this from sibling tools like approve_request. The prerequisite 'requires WRITE_ENABLED=true' is additional context that does not obscure the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when rejecting a pending approval, but it does not explicitly state when to use this tool versus alternatives like approve_request. No when-not-to-use guidance or alternative recommendations are provided, so it falls at the 'implied usage' level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, so the description doesn't need to restate safety. It does add the clarification that the operation 'marks' the asset as disposed/retired rather than deleting it, which is valuable. However, it does not disclose other behavioral traits like reversibility, required permissions, or side effects beyond the state change.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence plus a '[Write]' tag. It is front-loaded with the key action and resource, with no unnecessary words. This is an example of efficient, minimal description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write tool with full schema coverage and annotations, the description is sufficiently complete. It clearly states the action and its effect. However, since there is no output schema, a note about what the tool returns (e.g., updated record or success flag) would have been helpful but is not critical for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all parameters, covering 100% of the semantic meaning. The tool description does not add any additional parameter-related context, so the baseline score of 3 for high schema coverage is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Retire') and resource ('IT asset'), with a clarifying parenthetical ('mark as disposed/retired'). This clearly distinguishes it from sibling tools like update_asset or delete_record, which serve different lifecycle actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied by the name and description: use when you want to retire an asset. However, there is no explicit guidance on when to use this instead of alternatives such as update_asset or track_asset_lifecycle, nor any mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a destructive write operation (readOnlyHint=false, destructiveHint=true). The description adds value by specifying that retiring means 'mark as outdated', which clarifies the exact nature of the operation. However, it does not disclose additional side effects or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence, front-loaded with the action, and contains no redundant words. It is efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the core purpose and effect. It could be enhanced with usage context, but given the simplicity and annotations, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter article_id with its format (KB... or sys_id), and the description adds no additional parameter information. With 100% schema coverage, the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retire' with the resource 'knowledge article' and clarifies the meaning as 'mark as outdated'. This distinguishes it from sibling tools like update_knowledge_article or publish_knowledge_article.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention scenarios, prerequisites, or when not to use it. The only implicit context is the tool name itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only, not idempotent, and not destructive. The description adds the prerequisite ATF_ENABLED=true, which is useful configuration context. However, it does not disclose what executing a suite entails (e.g., running multiple tests, generating results) or how the outcome is returned, leaving the behavioral profile thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential purpose and a prerequisite. Every word earns its place, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain return behavior or next steps, but it does not. It fails to mention that running a suite may produce test results retrievable via get_atf_suite_result, nor does it note potential side effects or blocking behavior. For an execution tool, this is a significant omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides a complete description of the single parameter sys_id (System ID of the test suite), covering 100% of parameter semantics. The description does not add any additional meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Execute' with the resource 'ATF test suite', which clearly distinguishes it from siblings like run_atf_test, list_atf_suites, and get_atf_suite. The added prerequisite (ATF_ENABLED=true) further clarifies the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 (to run an ATF suite) and states a required condition (ATF_ENABLED=true). However, it does not explicitly contrast with related tools like run_atf_test or mention when to prefer one over the other, so it lacks all exclusion guidance but is still clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only adds '[Write]', which is redundant given readOnlyHint: false in the annotations. It does not disclose asynchronous behavior, return values, or side effects beyond what annotations already indicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with a [Write] tag, containing no redundant words. It is front-loaded and immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple trigger tool with all optional parameters described, the description covers the core purpose adequately. It lacks information about return values or asynchronous execution, but this is not critical for a straightforward action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (group, scan_type, ci_sys_ids) already have descriptions in the schema. The description's mention of 'specified CIs or groups' reinforces parameter meanings but adds no new information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Trigger a vulnerability scan') and the resource (vulnerability scan for specified CIs or groups). It distinguishes itself from sibling tools like run_discovery_scan or list_vulnerabilities by focusing specifically on triggering a vulnerability scan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context (for specified CIs or groups) and implies the tool's use case. It does not explicitly name alternatives or when-not-to-use, but the context is 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds that the tool matches items by keyword, which is a useful behavioral nuance, but it omits details like search scope, case sensitivity, pagination, or result ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the verb and states the core purpose without any redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with read-only annotations and full schema coverage, the description is adequate. It clearly identifies the domain and action; however, it does not mention return format or default behaviors beyond what the limit parameter already states.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for both parameters ('Search keywords' for query and 'Max results (default: 10)' for limit). The tool description adds no additional parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search'), resource ('service catalog'), and result ('items matching a keyword'), clearly distinguishing it from siblings like list_catalog_items or get_catalog_item. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (keyword search over the service catalog) but provides no explicit when-to-use vs alternatives such as list_catalog_items, natural_language_search, or ai_search. No exclusions or alternative guidance are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds the search scope (name, value, description) but does not elaborate on match behavior, pagination, or result format. With annotations covering the safety profile, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb and resource. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only search tool with full schema coverage and safety annotations, the description is sufficient. It clearly states what is searched, and the limit parameter is documented in the schema. It does not explain return values, but this is not required given the absence of an output schema and the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well documented. The description's mention of 'name, value, or description' essentially repeats the schema's search parameter description. No additional semantic value is added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('search') and resource ('system properties'), and defines the search scope ('by name, value, or description'). This clearly distinguishes it from siblings like list_system_properties (list all) and get_system_property (retrieve by exact name).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding properties by matching text, but does not explicitly state when to prefer this over list_system_properties or get_system_property, nor does it give any exclusion criteria. The context is clear enough to infer basic use, but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the WRITE_ENABLED=true requirement, which is useful environmental context. The annotations already indicate the operation is not read-only and not idempotent, so the description doesn't need to restate that. It does not describe side effects or whether a job run is created, but the additional context is on par with baseline expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that is front-loaded with the action and resource, followed by a necessary prerequisite in parentheses. Every word earns its place and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description is reasonably complete for an agent to invoke it. It notes the key requirement (WRITE_ENABLED) and the immediate/on-demand nature. The only minor gap is the lack of detail about return values, but this is not essential for a trigger action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage of the single parameter sys_id with a clear description ('Scheduled job sys_id to trigger'). The tool description adds no further parameter detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('immediately execute') and the resource ('a scheduled job'), and adds the important qualification 'on-demand' which distinguishes this from scheduled/automatic execution. It differentiates from sibling tools like list_scheduled_jobs or get_scheduled_job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for running scheduled jobs now rather than waiting for the schedule, and it mentions the WRITE_ENABLED=true prerequisite. However, it does not explicitly state when to prefer this over related tools like trigger_flow or how to identify the correct sys_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only, not destructive, and idempotent. The description adds the SCRIPTING_ENABLED requirement, which is useful context beyond the annotations. However, it does not disclose potential side effects of updating a business rule or what happens when the requirement is unmet, so it adds limited 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and includes a concise requirement. Every word earns its place, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple parameter set (2 params) and presence of annotations, the description is mostly sufficient. It adds the critical SCRIPTING_ENABLED prerequisite, and the schema documents the parameters clearly. It does not mention return values, but no output schema exists, so that is not a gap. Slightly more context about the update's effect would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both sys_id and fields have descriptions. The fields description adds meaning ('Key-value pairs to update (name, script, active, condition, etc.)'). Since the schema already carries the parameter semantics, the description adds no additional parameter information, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Update a business rule'. This distinguishes it from sibling tools like create_business_rule, list_business_rules, and get_business_rule. The additional requirement does not obscure the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite (SCRIPTING_ENABLED=true) that must be met, but does not explicitly mention alternatives or when-not-to-use. Usage is implied by the 'update' verb and the existence of create/list siblings, but lacks explicit exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and idempotentHint=true, so the safety profile is known. The description adds the WRITE_ENABLED=true requirement, which is a useful behavioral constraint not in the annotations. However, it does not disclose details about partial updates or side effects, but this is partially covered by idempotentHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that states the core action and a key requirement without any fluff. It is perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only 2 parameters, both documented, and annotations provide safety/idempotency context. The description adds the WRITE_ENABLED precondition. The absence of output schema and specific return behavior is a minor gap, but the description is sufficient for a straightforward update operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both user_sys_id and fields have clear descriptions. The tool description adds no extra parameter semantics beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update HR profile fields for a user' clearly identifies the action (update) and specific resource (HR profile), distinguishing it from read-only get_hr_profile and generic update_user. It also adds a crucial precondition (WRITE_ENABLED=true), 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context (updating HR profile) and notes a prerequisite (WRITE_ENABLED=true), but does not explicitly state when to use this over alternatives like update_user or other update tools. Usage is implied but not explicitly contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate this is a non-read-only, non-destructive, idempotent operation. The description adds the prerequisite that SCRIPTING_ENABLED must be true, which is useful operational context. However, it does not disclose further behavioral details such as what happens when the condition is unmet or any side effects beyond the update. With the annotations covering the safety profile, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and resource, with the requirement in parentheses. Every word is informative and there is no redundancy, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with two parameters and complete schema coverage, the description covers the core purpose and a key prerequisite. While it does not mention return values or error behavior, the lack of an output schema and the annotations clarifying safety make this reasonably complete. It could benefit from a brief note on what the response contains, but it is not critically incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for both parameters ('Key-value pairs to update' and 'System ID of the script include'). The description adds no additional parameter semantics beyond what the schema already states, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('a script include'), using a specific verb+resource pair that distinguishes it from sibling tools like create_script_include, get_script_include, and list_script_includes. The parenthetical requirement adds a useful constraint without obscuring the core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for updating script includes by its name and action, but it does not explicitly state when to use this tool over alternatives such as update_record or create_script_include, nor does it mention exclusions or alternative tools. The prerequisite SCRIPTING_ENABLED=true is a condition, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds the 'downstream impact' and 'change or outage' context, which is more specific than the raw annotation. However, it does not disclose details about how the analysis is performed (e.g., traversal depth, whether results are approximate, or if it reflects current state vs. simulated changes). With annotations covering the read-only nature, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly written sentence that immediately conveys the core purpose. It is front-loaded with the key verb and resource, and contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple tool with only two parameters and read-only annotations. However, it lacks information about the return format or what 'impact' concretely means (e.g., affected CI list, risk score). Given the absence of an output schema, the description could be more complete, but the core use case is still clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'ci_sys_id' and 'depth' have descriptive names and descriptions in the schema. The tool description adds no additional parameter context beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Analyze the downstream impact of a Configuration Item change or outage' with a specific verb ('Analyze'), a clear resource ('Configuration Item'), and a well-defined scope ('downstream impact'). It distinguishes itself from sibling tools like 'get_cmdb_ci' (which retrieves a single CI) and 'list_relationships' (which lists raw relationships) by focusing on impact assessment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for when to use this tool: when analyzing the downstream impact of a CI change or outage. It does not explicitly exclude or recommend against alternatives, but the specificity of the scenario (change/outage) gives sufficient guidance. No explicit alternatives are mentioned, so it does not reach a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds useful context about optional query scoping and the ability to compare either record counts or property values. However, it does not disclose prerequisites like what 'configured' instances entail or what happens when both optional parameters are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and front-loaded: two sentences that immediately state the action and purpose. There is no fluff, and every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters and no output schema, so the description needs to cover the main use cases. It does that, but it lacks a description of the return format or behavior when neither table nor property is specified. The mention of 'configured' instances is also vague, leaving a small but meaningful gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so parameters are already documented. The description adds a bit of context by mapping 'table', 'query', and 'property' to the comparison types, but this is redundant with the schema descriptions and does not provide significant additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Compare' and a clear resource 'two configured ServiceNow instances', and explicitly states what is compared (record counts and/or system property values). This distinguishes it from sibling tools like compare_record_counts or get_system_property, which operate on a single instance or a different scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case ('dev→prod drift detection and governance') and implies cross-instance comparison, which differentiates it from sibling tools. However, it does not explicitly state when not to use it or mention alternatives, though the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the write, non-idempotent, non-destructive nature is pre-disclosed. The description adds the requirement that SCRIPTING_ENABLED must be true, which is a useful behavioral constraint, and notes ES2021 support for scripts. Yet it does not disclose other behaviors like update set context or potential side effects beyond what openWorldHint already suggests.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the core action in the first sentence. The second sentence about ES2021 support is a minor detail that does not bloat the description, keeping it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, 4 required, no output schema) and good annotations, the description covers the essential action and a key prerequisite. However, it does not mention what the tool returns after creation, nor how it interacts with update sets or other environment settings. This leaves some gaps for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all 7 parameters, so the baseline is 3. The description's mention of ES2021 support is already present in the script parameter's schema description, so it does not add new meaning to the parameters. It adds no additional information about parameter formats or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new business rule', a specific verb+resource that clearly distinguishes it from siblings like update_business_rule, list_business_rules, and get_business_rule. The added prerequisite about SCRIPTING_ENABLED=true provides clarity about the operation's context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for creating new business rules and explicitly notes a prerequisite (SCRIPTING_ENABLED=true). It also provides guidance on script syntax (ES2021 async/await). However, it does not mention alternatives or exclusions, such as using update_business_rule for modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the [Write] prefix and the catalog item form scope, but does not disclose additional behavioral details such as whether duplicate policies are allowed or how conditions are evaluated. With annotations present, this level is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the verb and scope without any fluff. It is exactly as concise as it needs to be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple create operation with four parameters and no output schema. The description covers the core purpose but does not mention the return value or any special behavior (e.g., what happens if the catalog item ID is invalid). It is adequate but lacks additional context that would help an agent understand prerequisites or side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all four parameters, so the schema already documents each parameter's meaning. The description adds no parameter information beyond that, so it does not compensate or enhance the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('UI policy') scoped to 'a catalog item form', clearly distinguishing it from the generic create_ui_policy sibling. It is immediately obvious what this tool does and how it differs from similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this when creating a UI policy specifically for a catalog item form. It provides clear context but does not explicitly name alternatives or exclusions, such as 'for other forms use create_ui_policy'. This is clear enough for most cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is a write operation (readOnlyHint=false) and non-destructive. The description adds the key environmental requirement of SCRIPTING_ENABLED=true and the allowable script types, which are not present in annotations. This provides useful behavioral context beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the essential purpose and includes the prerequisite inline. Every word contributes value, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema is rich, but the description omits usage context and does not mention that 'active' defaults to true, which could lead to unintentional activation. It covers the basic purpose and requirement but lacks guidance on when to choose this tool over siblings or the side effects of creation, so it is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with individual parameter descriptions, so the description does not need to duplicate them. The parenthetical list of script types adds some context for the 'type' parameter, but overall the description adds minimal meaning beyond the schema, earning the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('client script'), and enumerates the specific script types (onLoad, onChange, onSubmit, onCellEdit). It distinguishes this tool from siblings like create_business_rule and create_script_include by being client-script-specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by naming the resource type, and mentions a prerequisite (SCRIPTING_ENABLED=true), but does not explicitly state when to use it versus alternatives like create_ui_policy or update_client_script. No exclusions or alternative recommendations are provided, leaving usage guidance primarily implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds the WRITE_ENABLED=true requirement and clarifies the row is staged for later transformation, which is useful. However, it does not disclose return values, error behavior, or validation details, so it provides only moderate additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant wording. It states the core action, the target, the purpose, and a necessary requirement in one concise line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential purpose and a prerequisite. However, it does not mention what the tool returns (e.g., the created row's sys_id), which is notable since there is no output schema. Error behavior and how the data parameter maps to columns are also not addressed, leaving some gaps for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters described adequately (staging_table has an example and a constraint; data is described as 'Key-value pairs'). The description adds no extra parameter semantics, but since the schema carries the burden, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Insert'), the target ('an Import Set staging table'), and the purpose ('for later transformation'), distinguishing it from generic record creation tools like create_record. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: the row is inserted for later transformation, implying it is a preparatory step before running a transform map. It also states a required prerequisite (WRITE_ENABLED=true). It does not explicitly mention alternatives or when not to use it, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive or idempotent. The description adds the key behavioral detail that it creates a case 'with all standard tasks', which goes beyond annotations. However, it does not disclose potential side effects, such as notifications or auto-assignments, even though openWorldHint=true suggests possible external effects. The annotations lower the bar, and the description provides some added context, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that clearly conveys the tool's purpose. It includes the unnecessary '[Write]' tag, but that is minor. It is concise, front-loaded, and free of fluff, earning a maximum score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple intent and all parameters are documented in the schema, but there is no output schema or mention of return values. The description does not clarify what happens after creation (e.g., whether a case ID is returned or if any prerequisites like employee existence are checked). Given the 100% schema coverage and existing annotations, the description is adequate but leaves some gaps in operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for all six parameters, so the baseline is 3. The description does not add any parameter-specific information, merely referring to the overall action. Since the schema already documents each parameter adequately, the description's contribution is minimal but not missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: creating an employee onboarding case, and specifies that it includes all standard tasks. This distinguishes it from sibling tools like create_offboarding_case and create_hr_case, 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.
Usage Guidelines4/5
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 this tool (when onboarding an employee), but it does not explicitly mention alternatives or exclusions. It is clear enough for the agent to infer appropriate use, but lacks the explicit 'use this instead of X' guidance that would earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive operation. The description adds the permission requirement (WRITE_ENABLED=true), which is useful context. However, it does not elaborate on side effects, the openWorldHint behavior, or what happens if the requirement is not met.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys both the action and a necessary condition. There is no fluff or redundant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description is minimal but sufficient for a basic create operation. It lacks information about return values or post-conditions, and the openWorldHint annotation remains unexplained, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (id, title, description, portal_sys_id) adequately described in the schema. The description adds no additional parameter semantics, so it stays at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('a new page inside a Service Portal'), which distinguishes it from sibling tools like create_portal_widget and create_portal. It specifies 'new page' to disambiguate from updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite ('requires WRITE_ENABLED=true'), indicating when the tool is usable. However, it does not explicitly mention alternatives or exclusions (e.g., 'use create_portal_widget for widgets'), leaving some guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, covering the safety profile. The description adds the SCRIPTING_ENABLED=true prerequisite, which is useful behavioral context beyond the annotations, but does not disclose other behaviors such as return formats or error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose and includes an important prerequisite. Every word earns its place, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal for a create tool with 9 parameters. It provides the core purpose and a key prerequisite, but does not explain the relationships between parameters (e.g., type vs. form_button/list_button) or typical usage patterns. However, the schema covers parameter semantics, and annotations cover safety, so it is adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 9 parameters, so the schema already documents semantics fully. The description adds no additional parameter-specific meaning beyond mentioning 'button or link', which loosely maps to the 'type' parameter but adds minimal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'UI Action (button or link) on a form', which distinguishes it from sibling tools like list_ui_actions, get_ui_action, and update_ui_action. It also adds a meaningful context by specifying the target placement (form).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit prerequisite: 'requires SCRIPTING_ENABLED=true'. This tells the agent when the tool is usable and implies a condition that must be checked before invocation. However, it does not explicitly mention alternatives such as updating an existing UI action, though that is inferable from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds useful context: it can run arbitrary server-side code, returns output, and requires WRITE_ENABLED. This goes beyond the annotations and helps the agent understand the operational implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a bit dense with multiple sentences, but each one serves a purpose: core function, supported APIs, output, use case, and requirement. It is front-loaded with the key action and remains readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the essential aspects: what it does, supported APIs, return value, use case, and configuration requirement. The note about WRITE_ENABLED and the supported API list make it fairly complete. Missing is a caution about side effects of arbitrary code execution, but annotations partially cover this via destructiveHint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both 'script' and 'scope' fully described in the schema. The description mentions using gs.print()/gs.info() for output, but this is already present in the schema description. The description adds no new parameter-level semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool executes a server-side script on the ServiceNow instance, and lists supported APIs. However, it does not distinguish itself from the sibling 'execute_background_script', which appears to serve the same purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to use the tool ('complex queries that cannot be expressed via REST') and states a prerequisite (WRITE_ENABLED=true). However, it does not mention when not to use it or compare it with the sibling execute_background_script.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safe read nature is known. The description adds that it returns 'details' and accepts a name or sys_id, but does not disclose behavior on not-found cases or response structure. Given the annotations, this is acceptable but not richly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single sentence of seven words, with no filler. It front-loads the verb and resource, making it immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-only lookup, the description fully conveys the operation and expected input. There is no output schema, but 'details' sufficiently implies the return of group attributes, and the context of a getter tool makes this sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents group_identifier as 'Group name or sys_id', and the description repeats the same information. No additional semantics are provided, so the baseline of 3 applies due to 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Find' with the resource 'assignment group details', clearly indicating a retrieval operation. It also specifies the lookup method 'by name or sys_id', distinguishing it from the sibling list_groups which presumably enumerates groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by name or sys_id' implies the tool is for when you have a specific group identifier, but it does not explicitly mention alternatives like list_groups or when not to use it. There is no exclusion or comparison with sibling tools, so guidance is limited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as readOnlyHint and openWorldHint, so the agent knows it is a safe read operation. The description adds that it returns audit history of changes, but provides no additional behavioral details such as pagination, ordering, or what fields are included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's purpose with no unnecessary words or repetitive content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, with clear annotations, fully documented parameters, and no output schema. The description sufficiently explains what the tool does for an agent to use it effectively, and there are no missing contextual details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters ('name' and 'limit') already described in the input schema. The description does not add any extra parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 audit history of changes to a system property.' It uses a specific verb ('Get') and a clear resource ('audit history of changes to a system property'), which distinguishes it from sibling tools like get_system_property or list_system_properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (to retrieve audit history) but does not explicitly state when to use this tool versus alternatives such as get_system_property or list_system_properties. No exclusions or context on when this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already provide readOnlyHint and openWorldHint, so the safety profile is clear. The description adds minimal behavioral context beyond the scope (current user) and does not disclose details like pagination or rate limits. Since there is no contradiction with annotations, a baseline score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, directly front-loaded with the action and scope. It contains no redundant words and earns its place without any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple list operation with one optional parameter, read-only annotations, and no output schema. The description sufficiently conveys the tool's purpose and scope; no additional detail is needed 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear description for the 'limit' parameter (max tasks, default 10). The tool description does not add any extra parameter semantics beyond what the schema already provides, so the baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List tasks') and the scope ('assigned to the currently configured user'), making it easy to distinguish from sibling tools like list_hr_tasks or get_task. It uses a specific verb and resource, fully clarifying what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving the current user's task list, but it does not explicitly state when to use this versus alternatives, nor does it mention any exclusions or compare with related tools. This is an implied usage rather than explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true and openWorldHint=true annotations, the description adds a meaningful behavioral constraint: it requires SCRIPTING_ENABLED=true. However, it does not disclose other potential behaviors such as pagination, return format, or what happens when no table filter is provided. The added value is modest but non-conflicting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core purpose and includes a bonus prerequisite. No redundant words or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a low-complexity list tool with a rich schema and safety annotations, but it omits some context: it does not state that the table parameter is optional, nor describe what the returned data looks like (though an output schema is absent). It does add the SCRIPTING_ENABLED requirement, which is valuable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 4 parameters are documented in the schema with clear descriptions (type, limit, table, active), so the schema already provides high coverage. The description does not add additional meaning about parameters beyond saying 'for a table', which mirrors the table filter. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('UI Actions'), and clarifies the resource by enumerating the types (buttons, context menus, related links). It also scopes the operation to 'for a table', which distinguishes it from sibling tools like get_ui_action (single record) and create/update_ui_action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this tool lists UI Actions, and it mentions a prerequisite (SCRIPTING_ENABLED=true) that guides when it can be used. It does not explicitly name alternatives, but the distinction from get/create/update siblings is implied by the action verb. Lacks an explicit 'use this instead of X' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false). The description adds the WRITE_ENABLED requirement, which is helpful, but it doesn't describe what publishing entails (e.g., state transition) or any potential side effects. Minimal behavioral context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that front-loads the action and includes a necessary prerequisite. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is adequate but not fully complete. It doesn't explain the return value or the publish state transition, and there is no mention of potential errors or valid article states, leaving some ambiguity about expected behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter sys_id as 'System ID of the article to publish', so schema coverage is 100%. The description adds no additional parameter information, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'publish' and the resource 'draft knowledge article', which distinguishes it from sibling tools like create_knowledge_article, update_knowledge_article, and retire_knowledge_article. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a key prerequisite (WRITE_ENABLED=true) and implies the use case of publishing drafts, but it does not explicitly name alternative tools or state when not to use it. This is clear context without formal exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and idempotentHint=true, which align with an update operation. The description adds the WRITE_ENABLED=true prerequisite, which is not present in annotations and is valuable context for the agent to check before invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with the core action front-loaded and the requirement in parentheses. No unnecessary words or repetition, every element contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not mention what the tool returns after the update, and it leaves the semantics of 'fields' partially open (though schema gives examples). It is sufficient for a basic update, but lacks guidance on return values or partial update behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes both required parameters, sys_id and fields, including the kinds of fields it accepts. The description adds no extra parameter details, so the schema carries the load; baseline 3 is appropriate given the 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing email notification', identifying the specific verb (update) and resource (existing email notification). This distinguishes it from sibling tools like create_notification, get_notification, and list_notifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'existing email notification' implies it is for modifying already-created notifications, and the requirement 'WRITE_ENABLED=true' provides a precondition for use. However, it does not explicitly mention when to prefer this over create_notification or how to handle alternative scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the behavioral context that WRITE_ENABLED must be true, which is a useful permission prerequisite not covered by the annotations. It also clarifies that the operation updates source code fields. However, it does not disclose potential side effects (e.g., widget behavior changes, validation, or response behavior), and the annotations already indicate it is a write, non-destructive operation. This is adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the action, target, and a critical prerequisite. Every word earns its place, with zero redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a mutation with no output schema, and the operation involves multiple potential code fields. The description covers the basic purpose and the WRITE_ENABLED requirement, but it does not explain the expected return value, whether the update replaces or merges fields, or any validation behavior. Given the simplicity of the schema (sys_id and a fields object), the description is passable but leaves some operational context undefined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with both sys_id and fields described. The tool description adds no extra parameter-specific meaning beyond what the schema already provides, such as the list of possible field keys. Thus, a baseline score of 3 is appropriate when the schema handles documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('Service Portal widget's source code'), clearly distinguishing it from related tools like create_portal_widget or get_portal_widget. The scope is precise, stating that it modifies source code rather than just any widget property.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool when you need to update an existing Service Portal widget's source code, as indicated by the word 'existing.' It also mentions the prerequisite 'requires WRITE_ENABLED=true,' which gives a concrete condition for use. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read/write and destructive profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds a specific operational requirement (WRITE_ENABLED=true) that is not in the annotations, which is useful context for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence, front-loaded with the verb and resource, and includes the prerequisite in parentheses. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple mutation with two well-documented parameters and annotations covering idempotency and safety. However, the description does not mention return values or behavior for non-existent incidents, and it relies on the schema for field details. It is adequate but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters, so the schema already explains what sys_id and fields mean. The description adds no additional parameter-level meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Update' and the resource 'security incident record', which is specific and distinguishes it from sibling tools like create_security_incident, get_security_incident, and list_security_incidents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a prerequisite (WRITE_ENABLED=true) but does not explicitly state when to use this tool versus alternatives. Usage context is implied by the tool name and purpose, but no direct exclusions or alternative references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses the WRITE_ENABLED=true requirement. This adds operational context not present in the annotations, though it does not cover idempotency or duplicate membership behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence that front-loads the purpose and includes a key requirement. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool, the description plus schema and annotations provide sufficient context. It names the operation and a key prerequisite, though it could mention what happens if the user is already in the group, but this is not critical given the sibling tool context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have clear descriptions ('System ID of the user' and 'System ID of the group'). The description adds no additional information beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a user to a group' with a specific verb and resource, distinguishing it from sibling tools like 'remove_user_from_group' and 'update_group'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a necessary prerequisite (WRITE_ENABLED=true) but no explicit guidance on when to use this tool versus alternatives like remove_user_from_group. Usage context is implied by the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly=false and destructive=false. The description adds useful behavior context: the requirement that WRITE_ENABLED=true must be set, and the condition that the request must be pending. This goes beyond the structured data and helps the agent understand prerequisites and state constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with a parenthetical requirement. It front-loads the action and contains no unnecessary words. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with annotations and full schema coverage, the description is largely sufficient. It states the action, the prerequisite, and the target state. It does not describe return values or failure conditions, but these are less critical for a straightforward approval action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for sys_id and comments. The tool description does not augment parameter meanings, so the schema carries the full burden. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Approve' with a clear resource ('a pending approval request'), which clearly distinguishes it from sibling tools like 'reject_request' and 'list_approvals'. The purpose is immediately obvious and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used for approving approval requests, but it does not explicitly contrast with alternatives such as 'reject_request' or state when not to use it. The WRITE_ENABLED requirement provides a constraint but no guidance on choosing between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already indicates a safe read operation. The description adds valuable behavioral context with 'in-memory grouping', revealing that the tool scans a limited set and groups in memory rather than performing a database-level query. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately conveys the action and method. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only optional parameters and read-only behavior. Given the annotations and full schema coverage, the description sufficiently covers the core purpose, though it doesn't describe the return format. It's still adequate for a basic discovery tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters are fully described in the input schema (100% coverage), so the description adds minimal new info about parameters. It does imply match_fields with 'specified fields' and limit with 'in-memory', but the schema already covers these.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Find') and resource ('duplicate CIs'), clearly distinguishing from sibling tools like cmdb_find_orphans and cmdb_find_stale. The phrase 'by matching on specified fields' further clarifies the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context (finding duplicates) but does not explicitly state when to use this tool over alternatives like search_cmdb_ci or cmdb_reconcile, nor does it mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the prerequisite 'requires WRITE_ENABLED=true' beyond the annotations, which already indicate this is a write operation (readOnlyHint=false). It does not disclose other behavioral traits like response format or side effects, but the annotation coverage lowers the bar.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and front-loaded with the action and resource. It avoids unnecessary detail and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema covers all parameters and annotations provide the safety profile. The description adds the key WRITE_ENABLED prerequisite. While it doesn't mention return values, the absence of an output schema and the straightforward nature of a create operation make this sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all 8 parameters. The tool description itself adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Create') and resource ('service catalog item'), making it unambiguous. It effectively distinguishes this from sibling tools like update_catalog_item and get_catalog_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for when to use this tool: it creates a new service catalog item and requires WRITE_ENABLED=true. It doesn't explicitly exclude alternatives, but the purpose is evident from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the created change request will be 'linked to a DevOps deployment,' which is a behavioral detail beyond the annotations. Annotations (readOnlyHint: false, idempotentHint: false, destructiveHint: false) already indicate a non-read, non-idempotent, non-destructive write operation, and the [Write] marker is consistent but redundant. The linking behavior is useful additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. The [Write] marker is redundant given the annotations, but the overall length is appropriate and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 7 parameters, all documented in the schema, and with annotations covering safety, the description covers purpose and the linking behavior. There is no output schema, but that is typical for create operations. It is sufficient for an agent to understand when and how to use the tool, though it could briefly mention required parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 7 parameters (100% coverage), so the baseline is 3. The description does not add parameter-specific details, though the phrase 'linked to a DevOps deployment' loosely implies that parameters like pipeline/artifact are relevant to establishing that link.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' with a clear resource: 'a change request linked to a DevOps deployment for change governance.' This distinguishes it from the sibling tool create_change_request, which is a general change request tool, by specifying the DevOps linkage and governance purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating change requests connected to DevOps deployments but does not explicitly state when to use it instead of alternatives like create_change_request, nor does it mention when not to use it. It lacks explicit exclusions or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the mutation is expected. The description adds the critical behavioral requirement of WRITE_ENABLED=true, which is not in the annotations. This is useful context that goes beyond structured data, though it does not describe side effects or response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that conveys the purpose and a key prerequisite. No wasted words; it is appropriately sized for a simple create operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, schema covers all parameters, and no output schema exists. The description provides the essential purpose and the WRITE_ENABLED constraint. It could have elaborated on expected return values, but for a straightforward create operation, the information is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for all three parameters (name, manager, description). The description adds no additional parameter meaning beyond what is already in the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' with a clear resource 'assignment group', distinguishing it from related group management tools like update_group or add_user_to_group. It also adds a useful operational condition (WRITE_ENABLED=true) that clarifies the intended use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the verb 'Create' and the tool name, but there is no explicit guidance on when to use this vs. alternatives such as update_group for existing groups. The WRITE_ENABLED requirement is a prerequisite, not a usage guideline. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (readOnlyHint=false) and adds a permission requirement (WRITE_ENABLED=true), but does not elaborate on side effects, return values, or other behavioral traits. Since annotations already indicate a write operation, the added value is moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the action and a key prerequisite with no filler or redundant information. It is front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with fully described parameters and safety annotations, the description is adequate. It could mention that the task is created as a child record of the HR case, but this is implied by 'within an HR case.' The absence of an output schema reduces the need for return-value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 4 parameters, so the description does not need to add parameter details. It provides the baseline level of clarity without adding extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('a task within an HR case'), which is specific and distinguishes it from sibling tools like create_hr_case (creates a case) and list_hr_tasks (lists tasks). The scope is precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context (creating tasks inside HR cases) and a prerequisite (WRITE_ENABLED=true), which implies when it can be used. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that this is a write operation (readOnly=false) and non-idempotent. The description adds the WRITE_ENABLED=true requirement, which is a useful operational constraint not fully captured by annotations. However, it does not disclose potential side effects, validation behavior, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that communicates the action and a key prerequisite without any redundant wording. It earns its place and is immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich 100% schema coverage and annotations (readOnly=false, idempotent=false), the description provides the essential extra context (WRITE_ENABLED=true). It does not describe return values, but no output schema exists and this is a common create operation, making the description adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for all 8 parameters (100% coverage), so the description does not need to add parameter-level semantics. The description itself adds no parameter context beyond the tool's purpose, which is acceptable given the schema completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action and resource: 'Create a new email notification definition'. This clearly identifies the verb (create) and the object (email notification definition), distinguishing it from siblings like update_notification and list_notifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool to create a new email notification. It also includes a prerequisite (WRITE_ENABLED=true) that sets a usage condition. While it does not explicitly mention alternatives or exclusions, the context is unambiguous for a create operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description is not required to restate that. The addition of the WRITE_ENABLED requirement provides operational context beyond the annotations, explaining a critical condition for the tool to function. No contradiction found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, around 14 words, with the purpose front-loaded and a parenthetical permission note. Every word earns its place; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 8 parameters and a fully described schema, the description covers the purpose and a key prerequisite. Annotations handle the safety profile. It does not explain return values or widget lifecycle, but the absence of an output schema and presence of complete parameter documentation make the description sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 8 parameters, so the schema already fully documents parameter semantics. The description's mention of 'template, CSS, and scripts' is a high-level summary but does not add 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create a new Service Portal widget' with a specific verb and resource, and lists the key content types (template, CSS, scripts). This clearly distinguishes it from sibling read/update tools like list_portal_widgets, get_portal_widget, and update_portal_widget.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite ('requires WRITE_ENABLED=true') which is a useful usage condition. However, it does not explicitly state when to use this tool versus alternatives like update_portal_widget, leaving usage to be implied by the verb 'create'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the write nature is known. The description adds the 'WRITE_ENABLED=true' prerequisite, which is a useful behavioral constraint. However, it does not mention other side effects or return behavior, though annotations 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and includes a key constraint in parentheses. Every word earns its place, with no redundant or vague language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with well-documented schema and annotations, the description adequately conveys purpose and a critical prerequisite. It does not explain return values, but no output schema exists, and the tool's behavior is straightforward. The openWorldHint annotation provides additional context about extensibility.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 5 parameters, so the schema fully documents their meaning. The description adds no parameter-specific guidance, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' and a specific resource 'outbound REST Message definition', clearly distinguishing it from sibling tools like list_rest_messages and get_rest_message. The term 'outbound' adds directional context, and 'definition' clarifies it creates a template, not a message instance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a prerequisite: 'requires WRITE_ENABLED=true', which is important guidance for the agent before invoking. It does not name alternatives, but given the sibling tool list, the create operation is clearly distinct from list/get functions, and no plausible alternative for creating a REST message exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false) and non-destructive behavior. The description adds the SCRIPTING_ENABLED=true requirement, which is valuable context beyond annotations, but it does not disclose potential side effects of script execution or behavior when the prerequisite is not met.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the core action, resource, purpose, and a key requirement without redundancy. Every word contributes to the tool's understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With complete schema descriptions, annotations covering mutation and safety, and simple create semantics, the description covers the essential purpose and prerequisite. It does not mention return values or post-create behavior, but that is not critical for a creation tool, especially with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with meaningful descriptions for all six parameters, so the description does not need to repeat them. The description adds no parameter-specific detail beyond the overall purpose, matching the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Create'), the resource ('UI Policy'), and its purpose ('to control field behavior dynamically'). This distinguishes it from sibling tools like create_ui_action or create_flow by specifying the exact artifact type and its behavioral goal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case ('control field behavior dynamically') and a concrete prerequisite ('requires SCRIPTING_ENABLED=true'). It does not explicitly name alternatives or state when not to use it, but the context is sufficiently clear for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly=false and destructive=false, and the description adds the optional switch behavior, which is a side effect beyond simple creation. The '[Scripting]' tag also provides context about intended usage. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler. It includes the essential action and an optional behavior, plus a brief context tag. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple create operation, the schema fully documents parameters, and annotations cover safety, the description is sufficient. It could mention return values, but this is not critical for a create tool and the openWorldHint and sibling tools provide additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and all parameters are already described in the input schema. The description does not add additional meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Create' and resource 'Update Set', clearly distinguishing it from sibling tools like list_update_sets, switch_update_set, and complete_update_set. The optional switch behavior is also stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies when to use the tool (to create an update set), but there is no explicit guidance about alternatives or when not to use it. Siblings like switch_update_set exist, but the description does not mention them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, openWorldHint=true, readOnlyHint=false, and destructiveHint=false. The description adds conditional creation logic ('create one automatically if none is in progress') and the '[Scripting]' context, which provides useful behavior 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no redundant text. The '[Scripting]' tag is a compact, informative qualifier. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple idempotent setup tool with one optional parameter and no output schema, the description covers purpose and trigger condition adequately. It does not mention return values, but none are expected, and the behavior is straightforward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%—the only parameter (default_name) is fully described in the schema. The tool description adds no additional parameter semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Ensure an active Update Set exists; create one automatically if none is in progress.' This specific verb+resource combination distinguishes it from siblings like create_update_set (which always creates) and switch_update_set (which changes the active set).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool—when an active update set is needed and auto-creation is acceptable—but it does not explicitly contrast with alternatives like switch_update_set or create_update_set, nor does it state when not to use. The usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 established. The description adds that it exports 'raw table data' as 'structured JSON', but doesn't disclose additional behavioral details like pagination or field handling beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that directly conveys the tool's purpose and output format. No redundant wording, front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the straightforward read-only nature, the schema covering all parameter details, and the annotations providing safety context, the description is sufficient. It could benefit from mentioning the default limit or the fact that 'raw' implies unprocessed records, but overall it's complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 adds no new semantic detail about the parameters themselves, only a general context of raw data export.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Export', the resource 'raw table data', and the output format 'structured JSON' with a purpose ('for use in external reports'). This distinguishes it from sibling tools like query_records or generate_report, which return data for different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for use in external reports' provides clear context for when to use this tool. However, it does not explicitly mention alternatives or exclusion criteria, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation, and the description consistently says "List" without implying side effects. It adds the key behavioral detail of filtering by artifact name, but it does not disclose the limit parameter's effect on result completeness or the return format. With annotations covering the safety profile, the description provides moderate added context, not extensive behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence that front-loads the verb and resource, then provides a clear purpose. Every word earns its place with no fluff or redundant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with two well-documented parameters and strong annotations, the description gives enough context to understand the tool's purpose and appropriate use case. It could mention the limit's effect on result completeness, but the schema already documents the parameter and the openWorldHint annotation covers non-exhaustive results, making the description sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes both parameters fully (name as artifact name or partial, limit as max records to scan with a default). The description's phrase "by name" aligns with the name parameter but adds no new semantics beyond what the schema already provides. Since schema coverage is 100%, the baseline is 3, and the description does not exceed that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ("List") and resource ("update sets that contain changes to an artifact"), making its function immediately clear. It also distinguishes itself from the sibling tool list_update_sets by focusing on artifact-specific filtering, and adds a practical rationale (knowing what is in-flight or captured for promotion).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase "before you touch it" clearly indicates when to use this tool: before modifying an artifact, to check for existing captured changes. It implies this is the right choice over generic listing alternatives like list_update_sets, though it does not explicitly name alternatives or exclusions, so it falls just 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds context about the content of the insight (metadata changes, role changes, field value changes), going beyond annotations. However, it does not address other behaviors like pagination, error conditions, or what happens if no previous successful run exists. Given annotation coverage, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys purpose and key scope, with examples and no redundant wording. It is front-loaded with the tool name and immediately specifies the resource and comparison nature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with one parameter and no output schema. The description explains the core output type (metadata changes) and the context (between last successful and failed run), which is sufficient for understanding. It could mention prerequisites (e.g., existence of a failed run) or more about the output format, but the essential behavior is clear given the annotations and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter result_sys_id is fully described in the schema (100% coverage) with 'System ID of the failed suite result'. The description does not add further semantics about the parameter, so the baseline of 3 applies as the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with resource 'ATF Failure Insight data' and clearly defines the scope: metadata changes between last successful and failed run, with examples (role changes, field value changes). This distinguishes it from sibling tools like get_atf_suite_result, which would return the suite result itself, and run_atf_test, which executes tests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use when investigating an ATF failure by comparing metadata changes across runs. It does not explicitly name alternatives or state when not to use, but the scenario is clear enough. Lacks explicit exclusions or pointer to complementary tools like get_atf_suite_result.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already marks this as a safe read operation, and the description adds the specific output fields (name, type, size). It does not contradict annotations, and the additional detail about return fields provides useful behavioral transparency beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the verb and resource, lists expected output fields, and includes the input identifier. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema, but the description compensates by listing the return fields (name, type, size) and identifying the input. It is complete enough for an agent to select and invoke the tool correctly without missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the only parameter (attachment_sys_id) with its type and description. The description merely restates 'by its sys_id' without adding new semantic meaning, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets metadata (name, type, size) for a specific attachment, identified by sys_id. It uses a specific verb and resource, and distinguishes itself from sibling tools like list_attachments 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific attachment sys_id and need its metadata, but it does not explicitly state when to use this tool versus alternatives like list_attachments. No exclusions or alternative references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description does not contradict them. The phrase 'including its variables' adds a small amount of context about response content, but the description does not disclose response format, error behavior, or other behavioral nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence, front-loaded with the action and object, and contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with one well-documented parameter and safety annotations, the description is mostly adequate. It conveys purpose and a key inclusion ('variables'), though without an output schema it could more explicitly describe the full response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the parameter sys_id_or_name already described as 'Catalog item sys_id or name'. The tool description adds no extra parameter-level semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' with the resource 'catalog item' and states it returns full details including variables. This clearly distinguishes it from sibling tools like list_catalog_items, create_catalog_item, update_catalog_item, and order_catalog_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies use when full details of a single catalog item are needed. It does not explicitly mention alternatives or exclusions, but the singular 'a catalog item' and 'full details' provide enough context to differentiate from listing or creating items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as readOnly and openWorld, and the description does not contradict them. The description adds the meaning of 'full details' and the identifier scope, but does not disclose return format, field coverage, or access requirements. With annotations covering safety, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence conveys the action, resource, and identifier format with zero wasted words. It is appropriately concise for a simple getter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only getter with no output schema, the description is sufficient: it identifies the tool uniquely, explains the one parameter's meaning, and is safe due to annotations. Minor gap: 'full details' is vague about which fields are returned, but this is not critical for a standard retrieval.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter with a description covering 100% of the semantics. The description simply repeats the schema's parameter description ('Change number (CHG...) or sys_id'), adding no new meaning. Baseline 3 applies due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('full details of a change request'), and clearly identifies the lookup mechanism ('by number (CHG...) or sys_id'). This distinguishes it from sibling list tools like list_change_requests and other getters by resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need full details of a specific change request, identified by its number or sys_id. It does not explicitly exclude alternatives (e.g., list_change_requests for browsing), but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the scope of the response (contacts and open cases count) but does not disclose other behavioral aspects such as error handling, authentication requirements, or pagination. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and key inclusions without any waste. It is concise and immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with a single parameter and read-only annotations, the description is reasonably complete. It specifies what the response will include (contacts and open cases count) and there is no output schema to explain. It could be slightly more explicit about the full set of fields, but it suffices for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only one parameter with a full description ('Account name or sys_id'), so schema coverage is 100%. The description does not add any additional meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('customer account'), and distinguishes it from sibling tools like list_csm_accounts (list vs. get) and get_csm_contact (account vs. contact). It also specifies the key contents ('contacts and open cases count'), 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about what to expect (account details, contacts, open cases count), implicitly indicating when to use this tool over list_csm_accounts or get_csm_contact. It does not explicitly name alternatives or exclusions, but the purpose is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 the specific metrics returned but no additional behavioral context such as time-window aggregation, how metrics are computed, or pagination. It does not conflict with annotations, but adds limited value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is efficient and direct. Every word contributes meaning—no filler, no redundancy. Perfectly sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description specifies the output (three metrics) and the resource (pipeline), which is adequate for a simple read-only tool. No output schema exists, but the metric names provide a reasonable expectation. It could be slightly more complete by mentioning the time window, but the schema supplies the 'days' parameter. Overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both 'days' and 'pipeline_sys_id' have descriptive text, so the schema carries the burden. The description does not add any parameter-specific detail beyond what the schema already states. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function with a specific verb ('Get') and resource ('metrics for a pipeline'), and explicitly names the three metric types (deployment frequency, failure rate, lead time). This distinguishes it from sibling tools like get_devops_pipeline (which retrieves pipeline details) and list_deployments (which lists individual deployments).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when aggregated pipeline metrics are needed. It offers clear context without explicitly naming alternatives or exclusions. It does not state 'use this instead of X' like the high example, but the resource and metrics are self-evident, making the use case clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 only that it returns 'detailed error logs' for 'failed flow executions', but does not disclose any additional behavioral traits such as pagination, ordering, or output format. This adds minimal value 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action ('Get') and object ('detailed error logs'), with no redundant words or filler. Every element earns its place, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter read-only tool with full annotations and no output schema, the description is sufficiently complete. It clearly states what is returned (detailed error logs) and for which executions (failed), which should allow an agent to select and invoke the tool. It could possibly describe the structure of the logs, but it's not essential for a basic read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with parameters flow_sys_id, days, and limit all having basic descriptions and defaults. The tool description does not add any extra meaning to these parameters; it simply restates the purpose. Since the schema carries the burden, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get detailed error logs for failed flow executions' uses a specific verb ('Get') and resource ('detailed error logs') with a clear scope ('failed flow executions'). It clearly distinguishes itself from siblings like list_flow_executions and get_flow_execution, which focus on execution metadata, not error logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for failed flow executions' provides clear context for when to use this tool: when you need logs from failed flows. It implicitly excludes successful executions, but it does not explicitly name alternatives or state when not to use other log-related tools like get_sys_log.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, and the description is consistent with a read operation. The description adds 'status and details' as the data scope, but does not disclose return format, possible status values, error behavior, or permissions. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the verb and object, containing no filler or redundant information. Everything included is useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-only getter with no output schema, the description adequately conveys purpose and the key identifier. It is slightly incomplete because it doesn't mention output format or alternatives, but given the low complexity this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents execution_sysid as 'sys_id of the flow execution to inspect', and the description adds no additional meaning beyond the phrase 'specific flow execution'. Schema coverage is 100%, so the description doesn't need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Get' and names the resource 'specific flow execution' along with what is returned ('status and details'). This clearly distinguishes it from sibling 'list_flow_executions' which lists multiple executions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clarifies that it applies to a specific flow execution, which implies it is for when an execution_sysid is already known. However, it does not explicitly mention alternatives such as list_flow_executions or get_flow, nor does it state exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds the useful 'full content' detail and the KB number format. However, it does not disclose behaviors like permission requirements, not-found handling, or response structure. Given the readOnly annotation covers safety, the description provides moderate added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the purpose and identifier requirements. No wasted words, and it is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, simple read operation), the description is sufficient. It clearly explains what the tool does and the input needed. A minor gap is the lack of return value details, but that is not critical for a straight 'get by ID' tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter is fully described in the schema ('Article number (KB...) or sys_id'), and the description repeats the same information without adding additional meaning. Since schema coverage is 100%, this is the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('full content of a knowledge article'), specifying the identifier format ('by number (KB...) or sys_id'). This distinguishes it from sibling tools like search_knowledge and list_knowledge_bases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It is clear that this tool should be used when you already know the article's number or sys_id. While it does not explicitly mention alternatives, the context of sibling retrieval/search tools implies it is the direct fetch-by-ID counterpart. The lack of exclusions or alternatives keeps it slightly below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint and openWorldHint, so safety is covered. The description adds the specific metrics returned but doesn't disclose additional behaviors like pagination, filtering, or permission requirements. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One succinct sentence that front-loads the purpose and key output metrics. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only analytics tool with one optional parameter and no output schema, the description is reasonably complete. It specifies what data is returned and the annotation covers safety. Minor gap: no mention of output format or default behavior beyond schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the 'days' parameter well-described. The description doesn't add extra parameter semantics, but the baseline of 3 applies since the schema fully documents the only parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Get' with resource 'mobile app usage analytics' and lists concrete metrics (sessions, active users, popular applets). This clearly differentiates from siblings like list_mobile_applets or get_mobile_app_config which deal with configuration/applets rather than analytics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool is for retrieving mobile app usage analytics. It doesn't explicitly name alternatives or provide exclusions, but the resource type and metrics are specific enough to signal appropriate use versus other analytics tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds no additional behavioral context about response format or potential edge cases. It does not contradict annotations but also doesn't go beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence, front-loaded with the action. No filler words. Perfectly sized for a simple getter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, the description covers the core purpose. No output schema exists, so the term 'details' provides some expectation but could be more explicit about the response structure. However, given the simplicity and annotation support, it's sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter with 100% coverage, including a description for sys_id. The tool description doesn't add extra meaning beyond what the schema already states. The term 'specific' aligns with the sys_id parameter, but no format or usage details are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (get details) and resource (specific mobile app configuration). It distinguishes from siblings like list_mobile_app_configs and create_mobile_app_config by focusing on a single configuration identified by sys_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you have a specific mobile app config sys_id and need its details. It lacks explicit exclusions or alternatives, but the word 'specific' clearly sets it apart from listing or creating. Given the simple getter nature, the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to repeat safety. It adds the user-scoping context but omits the fact that the state parameter allows filtering to approved/rejected states, not just pending ones. This is a behavioral nuance not fully disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It immediately communicates the core action and scope, maximizing clarity while minimizing length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with one optional parameter, full schema coverage, and read-only annotations. The description adequately covers the primary purpose and safety profile. It could be slightly more complete by noting that the default state is 'requested' and that filters can broaden to non-pending states, but overall it is sufficient for the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single 'state' parameter, including its enum values and default. The 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'List', the resource 'approvals', and the scope 'pending for the currently configured user', which distinguishes it from broader sibling tools like list_approvals and from approval actions like approve_request/reject_request. The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by scoping to the current user, which implies it should be used when needing the user's own approvals rather than a global list. However, it does not explicitly mention alternatives or exclusions, such as suggesting list_approvals for all users' approvals.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds 'including its formula' as useful content detail, but no further behavioral context such as permissions or response format. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with a clear verb and resource. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one parameter, well-covered schema, and read-only annotations. The description mentions the formula, giving a hint about return contents. While no output schema exists, the description is adequate for the tool's low complexity, but could mention other included details or response behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter sys_id_or_name is already described. The description does not add extra semantics beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('details of a specific Performance Analytics indicator'), and adds a distinctive detail ('including its formula'). This clearly distinguishes it from list_pa_indicators and other PA tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'a specific indicator' clearly implies usage when you need details for one indicator rather than a list. However, it does not explicitly name alternatives or exclusions, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds valuable behavioral context: the PA plugin prerequisite, the GET endpoint (implying read-only), and the behavior that a widget sys_id is resolved to its indicator. These details go beyond the structured annotations, though they don't describe response format or edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the verb and resource, followed by the endpoint and input details. Every sentence adds value, with no filler or repetition. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the description covers purpose, input methods, endpoint, and plugin requirement. However, there is no output schema, and the description does not specify the return format, pagination, or what happens if both indicator_sys_id and widget_sys_id are provided. It is sufficiently complete for a read-only analytics tool, but leaves some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters have descriptions in the schema (100% coverage), so the schema carries the main semantic weight. The description adds the useful clarification that indicator_sys_id and widget_sys_id are alternative input paths, but this is partially redundant with the widget_sys_id parameter description that already notes auto-resolution. No additional parameter semantics are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads Performance Analytics scorecard/indicator data, uses a specific verb ('Read'), and identifies the resource. It also names the underlying REST endpoint, which helps distinguish it from other PA-related tools, and clarifies the two input paths (indicator or widget sys_id). This makes 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use (requires PA plugin) and explains how to pass parameters, but it does not explicitly state when to prefer this tool over sibling tools like get_pa_scorecard or get_pa_indicator. There is no when-not-to-use guidance or mention of alternatives, so the usage guidance is partial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and open-world behavior. The description adds value by specifying the exact metrics and attributes returned (severity, vulnerability counts, MTTR), which helps the agent understand the output without needing an output schema. It does not disclose potential pitfalls like filtering behavior, but for a simple read-only dashboard the provided context 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the primary purpose and then lists the specific contents. It contains no redundant words and earns its place by efficiently conveying the tool's scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema, clear annotations), the description is mostly complete: it explains what the tool returns and the dashboard nature. It could be slightly stronger by explicitly noting that it provides an aggregated summary rather than detailed records, but the word 'dashboard' and the metric list largely convey this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single optional 'days' parameter, which already includes a clear description. The tool description does not add any additional parameter semantics beyond what the schema provides, hence 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'security posture dashboard', and enumerates the key metrics (open incidents by severity, vulnerability counts, mean time to resolve). This clearly distinguishes it from sibling tools like list_security_incidents or list_vulnerabilities, which focus on lists rather than an aggregated dashboard view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining a high-level security overview, but provides no explicit guidance on when to use this tool versus alternatives such as list_security_incidents or list_vulnerabilities. No exclusions or alternative references are mentioned, only an implied scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the safe read-only nature is known. The description adds 'full details,' which suggests comprehensive return data, but does not disclose specifics like response format, permissions, or any constraints beyond the lookup. It does not contradict annotations, but adds limited behavioral context beyond what structured data provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and resource. Every word is meaningful, no fluff. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema. The description covers its purpose and identifier use, but does not detail the return structure, which might be expected given the absence of an output schema. However, 'full details' adequately signals comprehensive data, and the annotations plus clear naming complete the picture sufficiently for a get-by-ID tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description already explains 'Security incident number (SIR...) or sys_id'. The description's 'by number or sys_id' adds no additional meaning beyond what the schema provides. There is no extra detail on formats, examples, or edge cases, so the description does not compensate beyond the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('security incident'), and the lookup mechanism ('by number or sys_id'). It is specific and distinguishes this from sibling tools like list_security_incidents (listing) and update_security_incident (mutation), as well as get_incident (generic incident).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a specific security incident via its number or sys_id, which is clear context. However, it does not explicitly mention alternatives or exclusions, such as when to use get_incident instead of this tool. The context is clear enough for an agent to infer the intended use, but explicit guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds that the tool returns a total record count (an aggregate value), which is not disclosed by the input schema. It does not mention edge cases or performance considerations, but the annotations cover the safety profile sufficiently.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence, front-loaded with the action and resource, with no unnecessary words. It is appropriately concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately defines the tool's purpose and return type (total count), and the schema covers parameter details. It could include an example or a note about performance on large tables, but given the simplicity and annotations, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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's mention of 'optional filters' aligns with the query parameter but adds no additional syntax or format details beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a total record count for a ServiceNow table, using a specific verb and resource. It distinguishes itself from siblings like query_records or get_record by focusing on aggregate counts rather than record retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for counting records with optional filters, but it does not explicitly mention when to prefer this tool over alternatives such as query_records or compare_record_counts. No exclusionary or alternative guidance is provided, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, which signal a safe, read-only operation. The description's 'Query' aligns with this but adds no extra behavioral context (e.g., rate limits, data source freshness, or response structure), so it stays at the baseline for annotation-covered tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the core purpose without filler. Every word adds information, making it extremely concise and well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only query tool with three self-explanatory parameters, the description, schema, and annotations provide sufficient context for an agent to select and invoke it. It lacks explicit return-format information, but the absence of an output schema is offset by the straightforward query nature and the readOnlyHint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already defines all parameters with descriptions. The tool description adds no additional semantic detail beyond naming content types (IOCs, threat actors, campaigns); it does not explain how to use 'type' or 'limit' beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with a specific verb ('Query') and identifies the exact resource ('threat intelligence data') with three concrete content categories (IOCs, threat actors, campaigns). It is unambiguous and distinct from sibling tools, which are mostly CMDB, HR, or ITSM related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'threat intelligence data' clearly indicates when this tool is appropriate, especially given no other threat-intel tool is listed among siblings. However, no explicit when-not-to-use or alternative is mentioned, so it doesn't fully reach a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 read-only operation. The description adds context about what the details include (layout and child elements), which goes beyond the annotations. It does not mention error handling or authentication, but for a simple get operation with readOnlyHint, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core action ('Get details') and includes relevant specifics without any waste or redundancy. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, the description is largely complete. It mentions what details are included (layout and child elements), and the schema covers the required parameter. No output schema exists, but the description hints at the return value. As noted, it does not address error cases or what happens if the page is not found, but those are not critical for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of the single parameter, stating 'UIB page sys_id'. The description does not add any additional parameter 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get details of a specific UI Builder page' with a specific verb ('Get'), resource ('UI Builder page'), and scope ('specific'). It also mentions the returned content ('including layout and child elements'), which adds clarity. This distinguishes it from sibling tools like list_uib_pages, create_uib_page, update_uib_page, and delete_uib_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by saying 'specific UI Builder page', but does not explicitly state when to use this tool vs list_uib_pages or provide any exclusions. There is no guidance on alternatives or when this tool is preferred, leaving the agent to infer from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description aligns with that. The description adds value by specifying the exact content returned ('intent and trigger phrases'), which provides behavioral/return details beyond the annotation. It does not mention openWorldHint semantics, but that is not a contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the action and key details. Every word earns its place with no redundant filler or repetition of structured data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id operation with one parameter and readOnly annotation, the description is adequate. It names the return specifics (intent and trigger phrases) and is complete enough for the agent to invoke correctly. A minor gap is lack of information about error behavior or response format, but the tool's simplicity reduces the need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter sys_id is described as 'Topic sys_id', which is clear. The description adds no additional parameter meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'Virtual Agent topic details', with specific content 'including intent and trigger phrases'. This distinguishes it from sibling list tools like get_virtual_agent_topics, which likely returns multiple topics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for fetching a single topic's details, but it does not explicitly state when to use it versus alternatives such as get_virtual_agent_topics or list_va_topics_full. No exclusions or alternative recommendations are provided, so the usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds the scope 'in the instance', which is useful context. However, it does not disclose any other behavioral details such as pagination, sorting, or whether archived suites are included. Given the annotations, this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose. No wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and the combination of a clear purpose, full schema coverage, and read-only annotations makes it adequately complete for an agent to invoke. The lack of an output schema is acceptable for a listing tool. The description could mention default behavior like the default limit, but the schema already notes default: 20, so this is covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters ('limit', 'query', 'active'). The description adds no additional semantic meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List ATF test suites in the instance'. The verb 'List' is specific, and the resource 'ATF test suites' is clearly identified. This distinguishes it from sibling tools like 'list_atf_tests' and 'get_atf_suite'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it lists ATF test suites, so an agent would know to use it when enumeration of suites is needed. It does not explicitly mention alternatives or exclusions, but the purpose is clear enough that an agent can differentiate it from related tools without additional guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds a bit of context about the scope ('individual test results within a suite run'), but it doesn't disclose behavioral traits like pagination behavior, result ordering, or what happens when no suite_result_sys_id is provided. It adds minimal value 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is concise and front-loaded with the action and object. Every word earns its place; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward listing tool with two optional parameters, good annotations, and no output schema, the description is mostly complete. It tells the agent what it lists, and the schema covers parameters. However, it does not mention the default limit or any implicit behaviors like whether results are exhaustive, but given the simplicity, this is a minor gap. It's adequate but not exceptionally rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already documented adequately. The description does not add extra meaning beyond what the schema provides; the term 'suite run' aligns with the suite_result_sys_id parameter but no additional semantics are given. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('individual test results within a suite run'), distinguishing it from siblings like list_atf_tests (which lists tests) and get_atf_suite_result (which gets the suite result itself). It precisely conveys the tool's scope and action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context ('within a suite run') which implies when to use this tool, but it does not explicitly state alternatives or exclusions. For example, it doesn't mention that get_atf_failure_insight is for failure details or that get_atf_test is for individual tests. This is clear context without direct comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true and openWorldHint=true annotations, the safety profile is already disclosed. The description adds no extra behavioral details beyond what the name and annotations imply (e.g., no mention of default limit, filtering behavior, or return format). It neither contradicts annotations nor offers significant additional context, so a middle score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and resource, with no filler or redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with four optional parameters and no output schema, the combination of a clear description, full schema coverage, and read-only annotations is sufficient. It does not state explicit pagination or default behaviors, but these are not critical for an agent to invoke the tool correctly, so a slight deduction for lacking detail like 'default 25' is warranted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all four parameters (limit, state, subject, recipient). The description itself does not add parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and identifies a clear resource ('outbound email log entries') with a stated purpose ('to track sent/failed emails'). This clearly distinguishes it from sibling tools like get_email_log (singular) and list_email_templates (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: it is for tracking sent/failed outbound emails. It does not explicitly reference alternatives or exclusion criteria, but the purpose clause provides clear context for when this tool would be appropriate, falling short of explicit 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already covers the safety profile. The description adds no additional behavioral traits beyond the schema-summarized filter options. It does not disclose pagination, ordering, or any other runtime behavior. With annotations present, this is acceptable but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that front-loads the core action and includes only essential filter details. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 required parameters and clear schema, the description is sufficient. It does not explain the return format or whether results are paginated, but given the simplicity and the presence of annotations, this is not a critical omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 merely restates that filters are optional but adds no extra meaning (e.g., valid state values, default behavior of filters). The schema's own descriptions ('Filter by state') are also vague, but the tool description does not compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List epics' with a specific verb and resource. It also mentions optional filters (project/state), distinguishing it from create/update epic tools. This is fully unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It indicates that filters are optional, giving context on when to use the tool (when you need epics with optional filtering). However, it does not explicitly name alternatives (e.g., list_stories for stories), nor specify scenarios where another tool would be preferred, so it falls short of an explicit when/when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description's read-only behavior is consistent. The description adds useful context beyond annotations by specifying 'recent' (indicating a time-bound result set) and 'processing status' (clarifying the kind of information returned). It does not contradict annotations and provides behavioral detail not captured by the metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence of 13 words. It is front-loaded with the primary verb 'List' and the resource, immediately conveying the tool's purpose. No word is wasted, and it avoids repetition of schema or annotation information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 with a well-described schema and safety annotations, the description is nearly complete. It specifies the subject (event log entries) and the key attribute (processing status), and the 'recent' qualifier sets expectations. However, it does not explicitly contrast with the related list_event_registry tool, which might be useful for an agent to disambiguate. Overall, it is sufficient for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with clear descriptions for all three parameters (limit, state, event_name). The description itself does not add any parameter-specific semantics, but that is acceptable given the high schema coverage. It does not compensate for anything missing, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists recent event log entries, specifying both the resource (event log entries) and the focus on fired events and their processing status. This differentiates it from sibling tools like list_active_events or list_event_registry, which serve related but distinct purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for viewing recent event logs and their processing status, but it does not explicitly state when to use this tool over alternatives, nor does it mention exclusions. Sibling tools such as list_event_registry or get_event_registry_entry are not referenced, leaving some ambiguity for an agent choosing among them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and openWorldHint=true, covering safety and scope. The description adds the 'all configured' scoping and multi-instance context, but does not describe pagination, return format, or other behavioral details. This is acceptable for a simple read-only list, but doesn't exceed annotation coverage significantly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and resource. Every word is informative, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is very simple (0 params, read-only), and the description accurately captures the core functionality. However, without an output schema, it doesn't mention what the returned list contains (e.g., instance names, URLs), which would be helpful. Overall, it's adequately complete for the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description provides no parameter information, but none is needed. The schema already shows no properties, so the description adds no parameter semantics beyond confirming the operation takes no input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('all configured ServiceNow instances'), clearly distinguishing it from sibling tools like get_current_instance or switch_instance. The parenthetical adds context about multi-instance support, reinforcing its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving all configured instances, but does not explicitly state when to use it versus alternatives like switch_instance or get_current_instance. There are no exclusions or alternative references, leaving the usage context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 with 'verify they are healthy,' suggesting the tool performs health checks, not just listing. This goes beyond the annotations without contradicting them, providing useful extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's purpose without unnecessary words. It earns its place and is easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter, no output schema, and clear read-only annotations. The description covers the main action and purpose. Minor ambiguity around what 'healthy' means (e.g., status field values) exists, but overall completeness is good for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter `active_only` is fully described in the schema (100% coverage) as 'Only show servers with status "Up".' The description does not add parameter-level detail, but baseline 3 is appropriate since the schema carries the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('List MID servers') and adds a specific purpose ('verify they are healthy'). This distinguishes it from other list tools in the sibling set, as no other tool targets MID servers specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when needing to view MID servers and confirm their health) but does not explicitly mention alternatives or exclusions. Given the tool's unique function among siblings, the lack of explicit alternatives is acceptable, but the guidance is not fully developed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 that results are unique categories with record counts, but it does not disclose additional behavioral traits such as pagination, ordering, or the data source. This adds some value but remains minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core action and includes a meaningful detail (record counts). It contains no fluff and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no params, no output schema), and the description explains the key return content (categories and counts). However, it lacks any mention of possible limits, formatting, or edge cases, which would make it fully complete. Still, it is adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4 per the rubric. The description does not need to explain parameters, and the schema is vacuously covered at 100%. The description adds no parameter-related info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('all unique property categories') with an additional detail ('record counts'), clearly distinguishing it from sibling tools like list_system_properties or get_property_history. It is not a tautology and precisely conveys what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (call this to get property categories with counts) but does not explicitly state when to use it vs. alternatives or provide exclusions. There is no mention of alternatives, which keeps the guidance 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint=true annotation already establishes the tool as a safe read operation. The description adds no extra behavioral context such as pagination behavior, ordering, or return structure. It is consistent with annotations but does not go beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the purpose without any filler or redundancy. It is perfectly sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with strong schema and annotations, the description is nearly complete. It defines the tool's purpose without explaining return values, which is acceptable given the output is an implied list. Some mention of returned fields or default behavior could push it to a 5, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'rest_message_sys_id' and 'limit' already described clearly in the schema. The description adds no additional parameter semantics, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a specific resource ('HTTP methods/functions defined within a REST Message'), clearly distinguishing it from sibling tools like 'list_rest_messages' and 'get_rest_message'. It unambiguously states what the tool returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you need the HTTP methods/functions belonging to a specific REST Message, requiring the parent sys_id. It does not mention alternatives or exclusions, but the context is clear enough for an agent to infer usage without confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 the underlying table name (m2m_story_dependencies), which provides context about the relationship structure, but it does not disclose ordering, return format, or directionality of links. This is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that packs the verb, object, and scope. The parenthetical table name is useful and not redundant. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a straightforward list operation with annotations and fully described parameters. Since there is no output schema, the description could ideally specify what a dependency link looks like, but the table name hints at many-to-many structure. This is sufficient for a simple tool, though not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description does not need to explain parameters. The phrase 'for a story' aligns with the 'story' parameter but adds no new semantic detail beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('dependency links'), and the scope ('for a story'), with the underlying table name (m2m_story_dependencies) for precision. This distinguishes it from sibling mutation tools like create_story_dependency and delete_story_dependency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implicitly conveys when to use this tool (to read dependencies for a story) and differentiates it from create/delete dependency siblings. However, it does not explicitly name alternatives or exclusions, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds the prerequisite SCRIPTING_ENABLED=true and explains what UI Policies are, providing context beyond the readOnlyHint annotation. It does not contradict the read-only hint and gives the agent actionable operational knowledge.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single, front-loaded sentence. Each parenthetical serves a purpose: defining UI Policies and stating a prerequisite. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description covers purpose, scope (table), and a key prerequisite. Without an output schema, it does not detail return structure, but 'List' implies a list result and the schema covers limit/filter parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters, so baseline is 3. The description does not add further parameter-specific meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States 'List UI Policies for a table' with a parenthetical defining UI policies as field visibility, mandatory, and read-only rules. This clearly distinguishes it from siblings like get_ui_policy (singular) and other list_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context 'for a table' and the prerequisite 'requires SCRIPTING_ENABLED=true', but does not explicitly mention alternatives such as get_ui_policy for a single policy or create_ui_policy for creation. Use case is implied rather than fully specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations provide readOnlyHint and openWorldHint, but the description adds valuable behavioral context: it queries the last 500 resolved records, groups by category, and matches keywords. This explains the mechanism and the 'suggest' nature of the output, going beyond what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and contains no fluff. It efficiently communicates both what it does and how it works without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description adequately explains the outcome ('suggest a category') and key behavior. It lacks details on return format or confidence but is sufficient for a read-only ML tool. A minor gap is not explicitly stating the dependency on resolved records, though it is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all three parameters with descriptions, so baseline is 3. The tool description adds meaning by explaining how parameters are used (e.g., 'matches input keywords' ties short_description to the matching logic, and the mention of 'table' as analysis scope). This is modest but useful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource: 'Auto-categorize a record based on its description by analysing resolved records of the same table.' This distinguishes it from sibling tools like categorize_incident (which is incident-specific) by emphasizing table-agnostic analysis and the use of resolved records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives like categorize_incident or ml_similar_incidents. The description implies usage for auto-categorization with ML, but provides no exclusions, prerequisites, or alternative comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, establishing this is a safe read operation. The description adds the return scope (history + accuracy trends over time) but does not disclose behavior like result ordering, pagination, or limits. This is acceptable but not rich 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 13 words. It is concise and every word adds meaning: 'Get' (verb), 'training run history and accuracy trends' (resource), and 'for an ML solution over time' (scope). No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, two-parameter tool with 100% schema coverage and no output schema, the description adequately communicates what is returned (training run history and accuracy trends). It does not detail output structure or pagination, but the tool's simplicity and strong annotations make the description largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both model_sys_id and days are documented in the input schema with meaningful descriptions. The description's phrase 'over time' loosely aligns with the days look-back parameter, but it adds no syntax or semantics beyond what the schema already provides, matching the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a specific resource ('training run history and accuracy trends') scoped to 'an ML solution over time'. This clearly distinguishes it from ML siblings like ml_evaluate_model, ml_train_*, and ml_predict_*, none of which retrieve training history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case: retrieve training run history and accuracy trends for a specific ML solution. However, it does not explicitly state when not to use it, nor does it name alternatives such as ml_evaluate_model for model evaluation or get_devops_insights for pipeline history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false and destructiveHint=true. The description adds the WRITE_ENABLED=true requirement, which is not present in annotations, providing extra context about a necessary precondition. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action immediately and includes a necessary requirement. No wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter destructive action, the description plus annotations are sufficient. It could mention the irreversible nature or what happens if the user is not in the group, but these are not critical for invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides full coverage of the single parameter member_sys_id with a clear description. The tool description adds no additional parameter meaning, so the baseline of 3 applies due to 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Remove' and resource 'a user from a group', clearly distinguishing it from sibling tools like add_user_to_group. The parenthetical adds a requirement without obscuring the core action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives, but the action itself strongly implies its purpose. The WRITE_ENABLED=true condition provides a prerequisite, giving some guidance beyond just the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only, open-world, non-idempotent, and non-destructive behavior. The description adds the prerequisite ATF_ENABLED=true, which is useful context, but it does not disclose potential side effects, response format, or whether execution is synchronous. With annotations carrying the safety profile, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and resource, with the prerequisite neatly parenthesized. There is zero redundant text, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the core purpose and a key prerequisite. It does not mention how to access results (e.g., via get_atf_test_result), but that is not strictly necessary given the low complexity and available sibling tools. Slightly more context about expected outcomes would make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with a description for the only parameter (sys_id as 'System ID of the test'). The description adds no additional parameter meaning 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Execute') and clearly identifies the resource ('a single ATF test'), which distinguishes it from sibling tools like run_atf_suite (single vs. suite). The phrase 'single' explicitly narrows scope, avoiding ambiguity with list/get operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a clear prerequisite: 'requires ATF_ENABLED=true', which is a useful when-to-use condition. However, it does not explicitly mention alternatives or when-not-to-use cases, though the sibling tool names (e.g., run_atf_suite) imply the distinction. The context is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=false, and the description adds the session-scoped nature of the switch. However, it does not elaborate on side effects or prerequisites, so it only partially adds 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, no filler. Every word contributes to the meaning and the description is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one fully documented parameter and no output schema. The description is sufficient for an agent to understand the operation's purpose and scope, though it does not reference how to list available instances.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single 'name' parameter with a clear description and example values. The tool description adds no additional parameter information, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (switch), the target (active ServiceNow instance), and the scope (for this session). It distinguishes from sibling tools like get_current_instance or list_instances by focusing on changing the active instance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating the action, but does not explicitly explain when to choose it over alternatives or mention any exclusions. Since the context is clear and the operation is distinct from related tools, this is a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide safety hints (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds the requirement that SCRIPTING_ENABLED=true must be set, which is useful beyond annotations. However, it does not disclose whether the update merges or replaces fields, nor does it mention potential side effects or permission requirements beyond the scripting flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the action and the requirement. It contains no filler or redundant wording, making it highly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool, the description covers the core purpose and a critical prerequisite. The schema explains the parameters, and annotations cover safety. It does not describe the return value, but no output schema exists and update tools often return minimal data. The main missing piece is explicit confirmation that only provided fields are updated, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both `sys_id` and `fields` have descriptions, with `fields` listing examples (active, script, roles, condition). The tool description itself adds no parameter-specific information beyond what the schema already provides, so it stays at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('an existing ACL rule'), and the word 'existing' differentiates it from creation tools like create_acl. It also adds a key prerequisite (SCRIPTING_ENABLED=true), 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating already-existing ACL rules, which distinguishes it from create_acl. It also states a specific prerequisite (SCRIPTING_ENABLED=true). However, it does not explicitly name alternatives or state when not to use this tool, so it lacks full exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnly=false, destructiveHint=false, and idempotentHint=true. The description adds the SCRIPTING_ENABLED prerequisite, which is useful for understanding a failure condition, but does not elaborate on other behaviors like partial updates or permissions. This adds some value beyond annotations but is not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb, and includes only the essential prerequisite. No wasted words; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate-complexity update tool, the description, schema, and annotations cover the core requirements. The fields object's internal structure is lightly specified, but the description gives sufficient information to select and invoke the tool correctly. A minor gap is lack of detail about return behavior, but no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 fields already described. The tool description adds no additional parameter meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Update) and the resource (client script), with 'existing' distinguishing it from creation. It also includes a key prerequisite (SCRIPTING_ENABLED=true), making the purpose unambiguous and distinct from sibling tools like create_client_script.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when updating an existing client script and mentions the required scripting-enabled condition. However, it does not explicitly name alternatives or state when not to use the tool, so while context is clear, it lacks explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds the WRITE_ENABLED requirement, which is useful context, but does not describe the update behavior or return value. With annotations covering safety, this is adequate but not extensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core purpose and a key prerequisite. Every word is useful and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter schema and strong annotations, the description is sufficient for an update operation. It could mention return values or error behavior, but these are often implicit for update tools and the WRITE_ENABLED constraint adds important context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions for both parameters. The 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'existing PA dashboard', distinguishing it from create_dashboard and get_pa_dashboard siblings. It also includes a prerequisite, reinforcing its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to update an existing dashboard) and provides a clear condition (requires WRITE_ENABLED=true). It does not explicitly mention alternatives like create_dashboard, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a useful prerequisite (WRITE_ENABLED=true) that is not in the annotations. However, annotations already indicate readOnlyHint=false and idempotentHint=true, so the update behavior is expected. No additional effects, errors, or response details are disclosed, so this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It clearly states the action, target, and a critical prerequisite without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter update tool with no output schema, the description is largely complete. It covers the prerequisite (WRITE_ENABLED=true) and the schema covers parameters. It does not describe return values, but that is not required given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters (sys_id and fields) are fully described in the input schema, so the description does not add new parameter semantics. The schema already documents sys_id as 'System ID of the problem' and fields as 'Key-value pairs to update'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'existing problem', which distinguishes it from sibling tools like create_problem and resolve_problem. It also specifies the scope (existing problem, fields) without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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: to update fields on an existing problem. It does not explicitly mention alternatives or exclusions, but the 'existing problem' phrasing implies it is not for creation or resolution, and the sibling tool names make the distinction obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive behavior. The description adds a meaningful operational constraint: requires WRITE_ENABLED=true. This is beyond the annotations and tells the agent that the environment must have write capability enabled for this tool to function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. It immediately states the purpose and the key prerequisite, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter update tool, the description plus schema covers the essentials. It mentions the fields object with example field names, and the WRITE_ENABLED prerequisite. No output schema exists, but returning the updated record is standard for update tools and not strictly necessary to document.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% - both sys_id and fields have descriptions in the schema. The tool description adds no parameter detail beyond the schema, so the baseline of 3 applies because the schema already documents the parameters sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' plus the resource 'scheduled job,' which clearly distinguishes it from sibling tools like create_scheduled_job, get_scheduled_job, trigger_scheduled_job, and list_scheduled_jobs. It leaves no doubt about what operation is performed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly compare this tool to alternatives or state when to prefer it over create/trigger. The WRITE_ENABLED=true requirement is a prerequisite, not a usage guideline. Usage is implied by the verb 'Update' and the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly=false, idempotent=true, and destructive=false, so the tool's mutation and safety profile are known. The description adds the SCRIPTING_ENABLED prerequisite, which is useful behavioral context, but no additional detail about side effects or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. The key action and prerequisite are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update operation with well-annotated safety and full schema coverage, the description is sufficient. However, the nested 'fields' object lacks detailed structure, and there's no output schema, so a bit more context about return values would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for both parameters (sys_id and fields). The description adds no extra parameter meaning, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('existing UI Action'), clearly distinguishing it from sibling tools like create_ui_action or get_ui_action. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a precondition (requires SCRIPTING_ENABLED=true) and implies the tool is for modifying existing UI Actions. It doesn't explicitly name alternatives, but the sibling list makes the appropriate use case clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate this is a non-read-only, idempotent, non-destructive operation. The description adds the prerequisite that WRITE_ENABLED must be true, which is useful operational context. It doesn't contradict the annotations, and it gives a bit more color about the fields affected. However, it doesn't describe side effects or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a parenthetical that packs the essential information—action, target fields, and a critical prerequisite—with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter update tool, the description plus full schema coverage and helpful annotations make it reasonably complete. The lack of an output schema means the agent doesn't know the return format, and there's no mention of partial-update behavior or error conditions, but these are minor gaps given the tool's simplicity and the annotations' coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both sys_id and fields, so the baseline is 3. The description's mention of state, risk acceptance notes, and remediation date mirrors the schema's 'etc.' and adds no new semantic detail beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's action ('Update') and resource ('a vulnerability entry'), and enumerates the primary fields (state, risk acceptance notes, remediation date), distinguishing it from sibling tools like get_vulnerability or list_vulnerabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to modify an existing vulnerability entry but provides no explicit 'when to use vs alternatives' or exclusions. For example, it doesn't reference get_vulnerability for reads or mention when not to use this tool. This is implied usage rather than explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the readOnlyHint annotation by noting it is 'real-time' and listing the multiple return formats (chart-ready data, Teams Adaptive Card, markdown table, summary). This helps the agent understand what to expect without being overly verbose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that efficiently conveys purpose, outputs, and read-only nature. No wasted words, and the structure is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema covers all parameters and annotations indicate read-only/open-world semantics, the description is fairly complete. It explicitly lists the return types (chart data, Adaptive Card, markdown table, summary), compensating for the lack of an output schema, though it does not detail any error conditions or edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all parameters, so the baseline is 3. The description does not add significant parameter-level meaning beyond the schema, though it provides usage examples for table and group_by.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Build a real-time chart of ServiceNow records grouped by a field' with concrete examples (incidents by priority, cases by state). It distinguishes from siblings by emphasizing grouping and the specific outputs (Adaptive Card, markdown table).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context and examples but does not explicitly state when to use this tool over similar alternatives like visualize_trend or aggregate_report. Usage is implied but not directly contrasted with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, which convey the mutation risk. The description adds no extra behavioral context such as permanence, permissions, or effect on dependent processes, so it relies entirely on annotations. It doesn't contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence is perfectly concise and front-loads the action. No wasted words, and the [Write] marker is a useful additional cue.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete tool with clear annotations and no output schema, the description is sufficient. It covers what the tool does and the key argument. The missing edge-case behavior (e.g., nonexistent property) is not necessary for a complete minimal description, and the annotations carry the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the 'name' parameter with description 'Property name to delete'. The description adds no additional parameter semantics beyond the schema, so baseline 3 applies given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Delete' and clearly identifies the resource 'system property' and the key 'by name'. This distinguishes it from sibling tools like get_system_property, set_system_property, and list_system_properties. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: when you need to remove a system property. It doesn't explicitly name alternatives or exclusions, but the context is clear given the sibling set. However, it lacks explicit guidance on when not to use it or alternatives like setting to null, so it's not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 a behavioral constraint not in annotations: the tool requires SCRIPTING_ENABLED=true, which is valuable context for invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the purpose and a critical prerequisite with no redundant or extraneous wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with no output schema, the description sufficiently states what is returned (full details and script body) and a key precondition. No additional context seems necessary 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter sys_id is fully described in the input schema with 100% coverage. The description adds no further parameter-specific semantics, so the schema carries the burden; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get), resource (business rule), and specific output (full details and script body). It distinguishes itself from sibling tools like list_business_rules, which only list, and create/update_business_rule, which mutate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a key prerequisite (requires SCRIPTING_ENABLED=true), which is useful context. However, it does not explicitly mention when to use this tool over list_business_rules or other alternatives, so the usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, covering safety. The description adds value by specifying the return content (impact, likelihood, controls), which is not in the annotations. It doesn't describe error cases or pagination, but for a simple read tool 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that is front-loaded with the action and resource, with no wasted words. It immediately communicates the tool's purpose and key return fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter get tool with read-only annotations, the description is complete. It specifies the identifier needed and the main fields returned. No output schema exists, but the description provides enough detail for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the only parameter, number_or_sysid, is described as 'Risk number or sys_id'. The description does not add additional semantic detail beyond this, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves a single GRC risk with specific fields (impact, likelihood, controls). The verb 'Get' and resource 'GRC risk' distinguish it from sibling tools like list_grc_risks, which lists multiple risks, and create_grc_risk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage—fetching details for a specific risk—but does not explicitly state when to prefer this over listing all risks or mention alternatives. It gives context about returned fields but lacks explicit exclusions or alternative tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds that it returns 'full details' and accepts number or sys_id, which is useful but minimal. No additional behavioral context such as error handling or prerequisite permissions is disclosed, but the annotations cover the core 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of about 12 words, highly efficient and front-loaded with the action. Every word adds value; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 parameter and no output schema, the description plus annotations are sufficient. The lookup methods and return scope ('full details') are clearly stated, and the context of siblings makes the tool's role unambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a clear description of the parameter. The description adds an explicit example 'HRCS0001234' and clarifies the accepted formats, but this is a minor enhancement over the schema. Since the schema already carries the meaning, baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and clearly identifies the resource as 'full details of an HR case'. It distinguishes itself from siblings like list_hr_cases (which lists) and create/update/close_hr_case (which modify), and get_hr_case_activity (which retrieves activity, not details). The example number format adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates how to specify the case (by number or sys_id) and gives an example format. However, it does not explicitly state when not to use this tool versus alternatives like list_hr_cases or get_hr_case_activity, so it lacks explicit exclusions. The context is clear but not fully differentiated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 the summary fields (purchased/installed/in use) but no additional behavioral traits like filtering or side effects. Credit for some context, but it largely relies on annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the purpose and key output details without any extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 one optional parameter. The description adequately defines what the tool returns (counts) and the scope (summary), which is sufficient in the absence of an output schema and complex params.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers the sole parameter fully: 'Software license sys_id (optional — omit for all)'. The tool description does not add parameter-specific meaning, but high schema coverage warrants a baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get license compliance summary' with specific output categories (purchased vs installed vs in use counts). This distinguishes it from sibling tools like list_software_licenses and get_license_optimization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a compliance summary, but does not explicitly mention alternatives or when not to use it. The context is clear enough for an agent to decide, but lacks explicit exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the NOW_ASSIST_ENABLED requirement, which is valuable context not captured in annotations. It does not describe error behavior or response format, but given the annotation coverage, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the action, resource, retrieval key, and a prerequisite. There is no extraneous information or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with one well-documented parameter, read-only annotation, and a clear prerequisite, the description is complete. The term 'definition' adequately indicates the return content, and no output schema is expected, so no additional return-value documentation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the sole parameter 'sys_id' with a clear description ('System ID of the skill'). The tool description merely repeats 'by sys_id' without adding further semantic detail. With 100% schema coverage, a baseline score of 3 is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear action ('Get'), a defined resource ('Now Assist skill definition'), and a precise retrieval criterion ('by sys_id'). It clearly distinguishes this from list_now_assist_skills, which would retrieve multiple skills, and from create/test sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the correct use case: fetch a specific skill when its sys_id is known. It also mentions the NOW_ASSIST_ENABLED prerequisite, giving important context. However, it does not explicitly contrast with list_now_assist_skills 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds useful behavioral context by naming the return fields (current value, target, trend direction). However, it does not disclose edge-case behaviors like handling of missing indicators or empty data, but for a simple getter with read-only annotations, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the tool's purpose and key output fields. Every word earns its place, with no filler, repetition, or tangential details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with full schema coverage and read-only annotations, the description is complete enough: it explains what the tool returns (scorecard data with value, target, trend) and implies the current-time scope. The lack of an output schema is adequately compensated by naming the returned attributes, and the sibling list contains related PA indicator tools, but this description clearly differentiates the scorecard focus.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all four parameters (period, include_scores, breakdown_sys_id, indicator_sys_id) with 100% coverage. The tool description itself does not add any parameter-level meaning beyond what is already in the schema, matching the baseline for fully described parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear action ('Get'), a precise resource ('current scorecard data for a PA indicator'), and explicitly lists the primary return fields ('current value, target, trend direction'). This distinguishes it from related tools like get_pa_indicator or get_pa_time_series, which focus on indicator details or time-series data rather than scorecard summaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'current scorecard data' implies that this tool is for retrieving current metric snapshots, but the description does not explicitly state when to prefer this tool over alternatives such as get_pa_time_series or list_pa_dashboards. No exclusions or contrasting guidance is provided, so usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safe read-only nature. The description adds the 'full details' aspect and identifier types, but does not disclose additional behavioral traits like authentication requirements, error behavior, or response format. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that immediately conveys the tool's purpose and lookup method. It is concise and front-loaded with no filler words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, clear schema, read-only annotations), the description is sufficiently complete. It says what the tool retrieves ('full details') and how to identify the job, which is enough for an agent to invoke it correctly in most situations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the parameter (sys_id_or_name: 'Job sys_id or exact name') with 100% coverage. The description repeats the same information without adding further semantic detail, so it provides no value beyond the structured schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's specific action: get full details of a scheduled job. It identifies the resource (scheduled job) and the lookup method (by sys_id or name), distinguishing it from sibling tools like list_scheduled_jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when you need full details of a specific scheduled job using a sys_id or exact name. It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to select it over list_scheduled_jobs for a targeted lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, openWorldHint=true) already communicate the safe read-only nature and external context. The description adds that the result includes CVSS score and affected CIs, which is useful but does not disclose any further behavioral nuances like error handling or permission needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action and object, and contains no redundant or filler information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter, a read-only annotation, and no output schema, the description is complete and sufficient. It clarifies what details are returned and matches the expected behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'number_or_sysid' is fully described in the schema (100% coverage) with examples. The tool description does not need to add more, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and identifies the resource ('specific vulnerability entry') with expected fields (CVSS score, affected CIs). It clearly distinguishes from sibling tools like list_vulnerabilities and update_vulnerability by focusing on retrieving a single entity's detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage is clear: use when you have a vulnerability number or sys_id and need full details. However, no explicit comparison with alternatives (e.g., list_vulnerabilities for browsing) is given, and there are no exclusions or when-not-to-use statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation with potentially evolving data. The description adds minimal extra context (what breakdowns are for) but does not disclose additional behavioral details such as pagination, authorization requirements, or potential performance characteristics. Given the strong annotation coverage, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, directly front-loaded with the action and object. It contains no filler or redundancy, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 with two optional parameters (fully described in the schema) and no output schema, the description plus the annotations cover all necessary context. It clearly states what the tool returns and its purpose, and the safety profile is fully covered by annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both 'limit' and 'query' have description text in the schema. The tool description itself does not mention parameters, but since the schema already documents them, the description does not need to compensate. Baseline of 3 applies here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List PA breakdowns (dimensions) available for segmenting indicator data.' The verb 'List' is specific, the resource 'PA breakdowns (dimensions)' is unambiguous, and the purpose 'segmenting indicator data' distinguishes it from sibling tools like list_pa_indicators (which lists indicators, not breakdowns) and create_pa_breakdown (which creates, not lists).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by explaining that these breakdowns are used for segmenting indicator data, making it evident when to use this tool (when you need to know available dimensions for segmentation). However, it does not explicitly mention alternatives or 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.
Behavior3/5
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 established. The description adds no further behavioral details such as pagination, default filtering, or response shape. The phrase 'available in the instance' slightly extends context but does not disclose behavior beyond what annotations or schema imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero wasted words. It immediately states the action and target resource, making it highly scannable and easily understood.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with no output schema, the description is sufficient. It conveys the purpose and scope, and the schema provides all parameter details. The annotations cover safety, so the agent has enough information to select and invoke the tool correctly without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all four parameters (limit, query, active, category), each with a clear description. The tool description itself does not add any additional parameter semantics, so the baseline of 3 applies since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'Performance Analytics (PA) indicators (KPIs)' and scope 'available in the instance'. This clearly distinguishes it from sibling tools like get_pa_indicator (singular fetch) and list_pa_breakdowns/list_pa_dashboards (other PA entities).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool is for listing all PA indicators available in the instance, which implies use when you need a collection of KPIs. It doesn't explicitly mention alternatives or exclusions, but the 'list' nature and sibling names provide sufficient context without being misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly=false and destructive=false, so the [Write] tag is redundant. The description adds the behavioral nuance that this is for drafts only and results in activation, which is useful but not deeply detailed. No additional risks or prerequisites are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with a clear verb and object. It is front-loaded with the core purpose and contains no filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write action with only 2 parameters (both documented) and no output schema, the description sufficiently explains the tool's function. The draft qualifier and the type field make the scope clear. No additional return-value or error details are necessary given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both 'flow_sys_id' and 'type' are already described in the schema. The description adds no parameter-specific information beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Publish (activate)') and the resource ('draft flow or subflow'). It distinguishes from siblings like create_flow, update_flow, and trigger_flow by focusing on activation of a draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you have a draft flow or subflow that should be published/activated. It does not explicitly list exclusions or alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds value by disclosing that it is real-time, read-only, and returns multiple output formats (chart-ready series, Teams Adaptive Card, markdown table, summary). This goes beyond the annotations and informs expected behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence states the core action and example; the second lists output formats. It is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even though there is no output schema, the description explicitly lists all return formats. With full schema coverage and clear annotations, it provides sufficient context 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameter meanings are defined in the schema. The description does not add extra parameter semantics beyond an example (incidents per day), so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds a trend line of record counts, provides an example (incidents per day), and lists distinct output formats (chart series, Adaptive Card, markdown, summary). This specific verb+resource+scope distinguishes it from sibling tools like trend_query or aggregate_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for visualizing record counts over time, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. No exclusions or alternative tool names are provided, so it is merely 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey the write nature (readOnlyHint=false) and non-idempotency. The description adds valuable context: the comment is customer-visible and requires WRITE_ENABLED=true. This goes beyond the annotations and gives the agent important operational knowledge.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that conveys the core action, scope, and a critical requirement. No fluff, front-loaded with the verb, and all words earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter tool with fully described schema and annotations, the description is complete enough for invocation. It does not discuss return values, but since there is no output schema and the operation is straightforward, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes each parameter, including 'Comment text (visible to end user/caller)'. The description adds little beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Add'), identifies the resource ('customer-visible comment'), and scopes it to 'any ITSM record'. It clearly distinguishes from the sibling 'add_work_note' by specifying the comment is customer-visible, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context ('customer-visible', 'any ITSM record') and a prerequisite ('requires WRITE_ENABLED=true'). It implies when to use this tool vs. internal work notes, but it does not explicitly name an alternative or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/open-world hints; the description adds non-obvious context about the Table API mechanism and the PI endpoint limitation. It does not contradict annotations and reveals that the result is a suggestion, not a persistent update.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences; the first states the purpose, the second adds an important limitation/alternative. No redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only suggestion tool with annotations, the description provides sufficient context including mechanism, output fields, and an important PI limitation. It could slightly improve by naming the exact sibling alternative or return structure, but current coverage is strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter coverage, so the baseline is 3. The main description does not add parameter-specific details beyond what the schema already provides; it only reinforces that short_description drives the heuristic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Suggest') and clearly identifies the resource (incident) and outputs (category, assignment group, priority). The phrase 'by analysing similar resolved incidents (Table API)' distinguishes it from sibling ML/PI-based tools by naming the mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context that this is a Table API heuristic and explicitly states that PI has no public REST prediction endpoint, directing model-based needs to PI on-record. It does not name sibling tools like ml_auto_categorize, but the boundary is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a destructive, non-read-only operation, so the description adds extra context by specifying the WRITE_ENABLED=true requirement and the precondition that the incident must be resolved. This goes beyond what annotations provide, though it omits details about side effects or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the verb and object, with a useful parenthetical for the permission requirement. No wasted words; every part contributes to understanding the tool's purpose and precondition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description covers essential aspects: what it does, when it can be used (resolved incident), and a system-level requirement. It does not explain return values, but since annotations and schema are already rich, this is sufficient. Minor gap is lack of detail on what 'closing' implies beyond the annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage on the single parameter sys_id, so the description need not elaborate. The description does not add any additional meaning about parameters, which is acceptable given the schema's clarity. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Close') and a specific resource ('incident'), and further qualifies it as 'resolved incident', which clearly distinguishes this tool from siblings like resolve_incident or update_incident. The parenthetical about WRITE_ENABLED adds a clear precondition, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: only for incidents that have been resolved. It also identifies a prerequisite (WRITE_ENABLED=true). However, it does not explicitly name alternatives or state when not to use it, so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the important prerequisite that SCRIPTING_ENABLED=true is required, which is not present in the annotations. It also clarifies that the tool creates a persistent access rule. Since annotations already indicate mutation (readOnlyHint=false) and non-destructiveness, the description provides extra context without contradicting the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the main action ('Create a new ACL rule') and includes the crucial prerequisite in parentheses. Every word earns its place; there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the full input schema and annotations, the description provides sufficient context for an agent to understand the tool's purpose and the key requirement (SCRIPTING_ENABLED=true). It doesn't mention return values, but with no output schema defined, this is not critical. The tool is moderately complex (8 params), but the schema fills in the details, making the description adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 8 parameters with individual descriptions (100% coverage), so the parameter semantics are well documented. The description itself adds little beyond the schema, only hinting at the use case rather than explaining any parameters. Thus, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create'), names the resource ('ACL rule'), and states the purpose ('to control access to a table or field'). It clearly distinguishes from sibling tools like list_acls, get_acl, and update_acl by emphasizing creation of a new rule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when creating a new ACL rule to manage access) and provides a critical prerequisite (SCRIPTING_ENABLED=true), but it does not explicitly mention alternatives or exclusions (e.g., 'use update_acl to modify an existing rule'). This gives clear context without full when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint false, openWorldHint true), the description adds value by disclosing hard prerequisites (feature flags must be enabled) and a side effect (auto-generated ACLs). It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the primary action and includes only high-value context: prerequisites and optional behavior. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward create tool with a fully described schema and annotations, the description is sufficiently complete: it states purpose, prerequisites, and a key side effect. The lack of an output schema is not a major gap since create tools conventionally return the created object, though mentioning that explicitly would strengthen it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains all four parameters. The description's mention of 'optional auto-generated ACLs' basically restates the auto_generate_acls property description without adding new parameter-level detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Create an AI agent definition', which clearly distinguishes this tool from sibling tools like get_ai_agent, list_ai_agents, and create_agentic_workflow. The mention of 'optional auto-generated ACLs' adds precision about what the creation involves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear operational context by stating the required flags (NOW_ASSIST_ENABLED + WRITE_ENABLED) and the optional ACL generation behavior. However, it does not explicitly name alternatives or state when not to use this tool compared to similar creation tools like create_agentic_workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and non-idempotent. The description adds valuable context beyond those annotations: the automatic generation of approval requests, the WRITE_ENABLED=true requirement, and the use of the sysapproval_rule table. This gives the agent a better sense of side effects and prerequisites without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, followed by the permission requirement and table detail. Every word earns its place; there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (7 params all documented, write operation) and the presence of annotations, the description covers the essential behavioral context: what the tool does, a key prerequisite, and the storage table. It does not describe return values, but the lack of an output schema makes that less critical. A small omission is not explicitly mentioning that 'condition' blank means always fire, but that is present in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with each of the 7 parameters described. The description does not provide additional parameter-level detail beyond what the schema already states (e.g., it references 'conditions' which maps to the 'condition' field, but that field is already described as 'Encoded query that determines when the rule fires'). With high schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear, specific action ('Create an approval rule') with a precise behavioral outcome ('automatically generates approval requests when a record matches given conditions'). It distinguishes this tool from siblings like approve_request or create_flow by focusing on rule creation rather than individual approval or flow automation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: when a user needs to set up an automated approval rule based on record conditions. It also notes a prerequisite (WRITE_ENABLED=true) and mentions the underlying table, which aids in context. However, it does not explicitly name alternatives or exclusions (e.g., 'use create_flow for complex routing'), so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-readonly operation. The description adds the 'requires WRITE_ENABLED=true' constraint, which is a meaningful behavioral detail beyond the annotations. It does not contradict the annotations and provides 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the verb and resource. Every word serves a purpose, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a comprehensive schema and annotations, the description is mostly sufficient for a simple create operation. It lacks details about return values and does not distinguish from specialized create tools, but these are minor gaps given the well-structured input schema and safety annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter already has a clear description. The tool description adds no additional parameter-level semantics, making a baseline score of 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new HR Service Delivery case' with a specific verb and resource. It distinguishes itself from sibling tools like update_hr_case, list_hr_cases, and close_hr_case by indicating a create operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite (WRITE_ENABLED=true) that informs when the tool can be used. However, it does not mention alternatives such as create_onboarding_case or create_offboarding_case, nor does it specify when to prefer them over this generic creation tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that this is a write operation (readOnlyHint=false) and non-idempotent. The description adds the WRITE_ENABLED configuration requirement, which is a useful behavioral detail about a potential failure condition. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded. Every word earns its place, providing the core action and a critical requirement without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the full parameter schema and annotations, the description provides adequate context for invoking the tool: it states the creation action and the WRITE_ENABLED prerequisite. It does not describe the return value or side effects beyond the openWorldHint annotation, but the essential information is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides comprehensive descriptions for all 9 parameters (100% coverage). The tool description itself adds no additional parameter-level meaning, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('incident record'), which distinguishes it from siblings like get_incident and update_incident. The addition of the WRITE_ENABLED requirement adds specificity and context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended use obvious ('create a new incident record') and mentions a key prerequisite (WRITE_ENABLED=true). It does not explicitly name alternatives, but the context is clear enough that an agent would know when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-idempotent behavior. The description adds the requirement of NOW_ASSIST_ENABLED and WRITE_ENABLED, which is beyond the annotation data and helps the agent understand necessary preconditions for 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no filler, front-loads the purpose and prerequisites. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the full schema coverage, annotations, and lack of output schema, the description adequately covers the tool's purpose and constraints. It could explicitly mention that this creates a persistent definition, but that's implied; slightly under-specified regarding return value, but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema provides 100% coverage of all 6 parameters with individual descriptions. The tool description adds no additional parameter semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource pattern ('Create a Now Assist skill definition') and clearly distinguishes from sibling tools like get_now_assist_skill and list_now_assist_skills by indicating the creation action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by listing prerequisite flags (NOW_ASSIST_ENABLED + WRITE_ENABLED), but it does not explicitly mention alternative tools or when not to use it. The creation verb implies the usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds a meaningful permission requirement (`WRITE_ENABLED=true`) and clarifies the conceptual domain, which is more than the annotations alone provide. No contradiction detected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences immediately state the operation, target table, prerequisite, and domain concept. Every phrase earns its place; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, prerequisite, and domain context, and the schema covers all parameters. There is no output schema, but for a create operation this is acceptable. It could mention return values or duplicate behavior, but that gap is partially covered by annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all four parameters with descriptions, examples, and defaults (100% coverage), so the baseline is 3. The description adds framing about how breakdowns are named and used but does not materially go beyond the schema's parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 specific resource ('PA breakdown' on `pa_breakdowns`), and clearly explains what a breakdown does semantically ('slice an indicator by a dimension'). This distinguishes it from sibling tools like `create_pa_indicator` and `list_pa_breakdowns`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a clear prerequisite (`WRITE_ENABLED=true`) and provides a concrete use case with examples ('Assignment group or Category'). It does not explicitly exclude alternatives or name sibling tools, but the context is sufficient for basic selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, etc.), it discloses the WRITE_ENABLED requirement and the need to run a PA job afterward, which clarifies the indicator isn't immediately populated. It doesn't cover return values, but gives useful 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences deliver purpose, prerequisite, key configuration, and a follow-up step. No filler; minimal and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description doesn't explain what the API returns, but it covers the creation flow and post-creation step (PA job). It could mention the response format, but the information provided is sufficient for core usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are documented in the schema. The description adds only a high-level summary ('facts table, aggregation and conditions') without new parameter-level details, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it creates a PA indicator/KPI on the pa_indicators table, with a specific verb and resource. It also differentiates from sibling tools like list_pa_indicators and create_pa_breakdown by naming the target table and core configuration fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context that it's for creating indicators, and hints at the follow-up action ('collect data via a PA job afterward'). Also gives a prerequisite (WRITE_ENABLED=true). However, it doesn't explicitly name alternatives or exclusions, so a 5 isn't warranted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and not idempotent. The description adds the critical prerequisite 'requires WRITE_ENABLED=true', which is beyond the structured annotations. It does not detail what happens on success or failure, but the key behavior—creating a new configuration—is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that states the tool's purpose and a key prerequisite. No filler or redundant content. 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward create operation with a fully self-describing schema and clear annotations, this description is adequately complete. It covers the action, the resource, and a required precondition. It does not mention return values, but no output schema is provided, and typical create behavior is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with each parameter already described (e.g., 'sys_id of the logo attachment record', 'URL path segment for the portal'). The description adds no additional parameter-level information, so the schema carries the full burden, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new Service Portal configuration', which specifies a concrete action (create) on a specific resource (Service Portal configuration). This distinguishes it from sibling tools like create_portal_page, which creates a page within a portal, and list_portals, which retrieves existing portals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for when to use this tool: when a new Service Portal configuration needs to be created. It also adds a prerequisite ('requires WRITE_ENABLED=true'), which is useful guidance. However, it does not explicitly mention alternatives or when not to use it, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, etc.), the description adds useful context: the WRITE_ENABLED=true permission requirement and the dry_run=true preview behavior. This discloses the need for write privileges and a safety valve for testing, which 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, and no extraneous information. Every word earns its place, including the permission caveat and dry-run note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with high schema coverage, the description adequately covers the action, permission, and dry-run option. It does not describe the return value, but no output schema exists and the description is otherwise complete 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all three parameters (table, fields, dry_run), so the description does not need to repeat them. It adds slight value by explaining dry_run's purpose ('preview the resolved payload'), but does not enrich table or fields beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' with the resource 'a new record in any ServiceNow table,' clearly distinguishing it from sibling update/delete/query tools. The mention of 'any ServiceNow table' signals generality, which differentiates it from specialized creates like create_incident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for generic record creation across tables and notes the prerequisite WRITE_ENABLED=true. It does not explicitly mention alternatives like bulk_create_records or specialized create tools, but the generic scope is clear enough for an agent to infer appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate this is a write operation (readOnlyHint=false, idempotentHint=false). The description adds the specific WRITE_ENABLED=true prerequisite, which is useful permission context. It does not disclose further side effects like script execution behavior, but given the annotations, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that states the action and a key requirement. It is front-loaded and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex with 6 parameters and no output schema, but the description plus schema cover the primary purpose and requirements. It could mention the return value (e.g., the created job ID), but for a mutation tool with good parameter documentation, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for all 6 parameters, so the schema carries the heavy lifting. The description's phrase 'scheduled script execution job' adds a bit of context about the script parameter's purpose but does not provide additional formatting or semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' and identifies the resource as 'a new scheduled script execution job', clearly distinguishing it from sibling tools that list, get, update, or trigger scheduled jobs. It also includes a prerequisite requirement, adding to its clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the requirement WRITE_ENABLED=true, which guides when the tool is usable. However, it does not explicitly name alternatives or describe when not to use it, though the sibling tool names imply related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) and non-destructive behavior. The description adds the WRITE_ENABLED precondition and the scope uniqueness requirement, which are not in annotations. It doesn't disclose return values or side effects, but it adds operational context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the verb and resource. Every sentence provides necessary information: the action and the critical prerequisites/constraints. No redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter create tool with no output schema, the description covers the most critical operational constraints (WRITE_ENABLED, scope uniqueness) and the full schema provides parameter details. It does not mention return values or post-creation behavior, but the annotations and schema fill most gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 8 parameters, so the baseline is 3. The description adds a slightly more specific naming pattern for scope (x_<vendor>_<appname>) but otherwise relies on the schema to convey parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('scoped application in App Studio'), using a specific verb-noun pair. It distinguishes from sibling tools like list_scoped_apps and update_scoped_app by focusing on creation and adding the scope prefix pattern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear prerequisite (WRITE_ENABLED=true) and a naming constraint (scope must be unique and follow x_<vendor>_<appname>), which are conditions for use. It does not explicitly name alternatives or when-not-to-use, but the domain is clear enough for an agent to choose this over list/get/update.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a key behavioral requirement beyond the annotations: 'requires WRITE_ENABLED=true'. Since readOnlyHint=false already indicates a write operation, this prerequisite supplies additional context about the environment needed for success. It does not contradict any annotations and provides useful operational detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the action, resource, and a key requirement. Every word is essential, with no filler or redundancy. It is well-structured and front-loaded for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with full schema coverage and annotations, the description is largely complete. It covers the core purpose and a critical prerequisite. While it does not describe return values or additional behavioral details, these are not essential given the schema and annotations. A slightly richer description could mention what happens on success, but it is not a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all 6 parameters, covering 100% of them. The description itself does not add any parameter-level details, so the schema carries the full burden. According to the rubric, a baseline of 3 is appropriate when schema coverage is high and the description adds no extra parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' and identifies the exact resource 'agile story/user story'. This clearly distinguishes it from sibling tools like create_epic, create_scrum_task, and create_story_dependency, which operate on different resource types. The purpose is unambiguous and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for creating stories, implying it is the appropriate choice for that task. It also states a prerequisite (WRITE_ENABLED=true), which helps the agent decide if it can use it. However, it does not explicitly exclude alternatives or mention 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds valuable context beyond the annotations: the WRITE_ENABLED requirement and the dry_run preview option, which inform the agent about safety and prerequisites. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and every sentence contributes value (scope, prerequisite, dry_run safety). No redundant or filler content exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description covers the essential context: the operation, the prerequisite, and a safety mechanism. It does not describe the return value on successful deletion or error cases, but given that annotations and schema handle the safety profile and parameters, the description is sufficiently complete for a simple delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema coverage is 100%, the schema already documents all three parameters (table, sys_id, dry_run) with clear descriptions. The tool description adds no additional meaning for the parameters; it merely restates the dry_run concept already present in the schema. Therefore, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('a record from any ServiceNow table'), which clearly distinguishes it from siblings like update_record, get_record, and create_record. The scope ('any ServiceNow table') makes the tool's function immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite (WRITE_ENABLED=true) and explains the dry_run parameter as a preview mechanism. It implies when to use the tool (to delete a record) but does not explicitly mention alternatives or exclusions, though the sibling list contains no other delete tool, making the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the actual command executed (`npx @servicenow/sdk build`) and the required environment prerequisites. This goes beyond the annotations, which only indicate readOnly and openWorld hints. No contradiction with annotations is apparent, as the build likely does not mutate the ServiceNow instance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise, containing two sentences that front-load the purpose and command. Every element adds value, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple build tool with one optional parameter and no output schema, the description is largely complete. It states the purpose, command, and prerequisites. A minor gap is the lack of mention of typical build results or side effects, but this is not critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With a single optional parameter and 100% schema description coverage, the schema already fully documents the 'directory' parameter. The description does not need to add further parameter details, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Build a ServiceNow fluent/now-sdk project' and specifies the exact command executed. This distinguishes it from sibling tools like fluent_validate or fluent_init, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides essential usage context by listing required environment variables (FLUENT_ENABLED and WRITE_ENABLED). It implies when the tool should be used (building a project) but does not explicitly contrast it with alternatives. However, the specificity of the build command makes the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description adds behavioral detail: it runs an external npx command and requires an environment variable. This gives the agent actionable expectations about side effects and prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The purpose is front-loaded, and the command and requirement are stated efficiently. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter, no output schema, and safety annotations, the description covers purpose, command, and a necessary prerequisite. It doesn't describe return values or error scenarios, but these are not critical given the tool's simplicity and the existing annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'directory' is fully described in the schema (100% coverage), so the description doesn't need to add parameter details. It adds nothing beyond the schema, matching the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates a ServiceNow fluent/now-sdk project, using the specific verb 'Validate' and naming the resource. It also gives the exact command run, which distinguishes it from sibling tools like fluent_build or fluent_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context (validation of fluent/now-sdk projects) and a key prerequisite (FLUENT_ENABLED=true). It doesn't explicitly mention alternatives or when-not-to-use, but the purpose is distinct enough that no exclusions are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, which the description does not contradict. The description adds useful context beyond annotations by specifying output characteristics (branded, includes charts/tables/ServiceNow links) and the two input modes (content vs. sections).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main verb and resource. Each sentence adds value: what it does, when to use it, and the two modes. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters but no output schema, the description adequately covers what the tool does, when to use it, and the two main input modes. It does not explain return values or error conditions, but that is not explicitly required and the description is otherwise complete for the described complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description adds minimal extra meaning by summarizing the content/sections distinction, but it does not introduce new parameter-specific details beyond what the schema already provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Generate a branded PDF or PPTX report') on a specific resource ('capability analysis results'). It distinguishes itself from sibling tools by emphasizing management-ready output with charts, tables, and ServiceNow links, and by explaining the single vs. multi-capability modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use: 'Call this after completing a scan, review, or audit'. This clearly defines the intended context. However, it does not explicitly mention when not to use it or alternatives, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds a useful behavioral dependency (SCRIPTING_ENABLED=true) and clarifies the return content (full details and script body), going beyond what the 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the verb and resource, then adds a necessary prerequisite without unnecessary wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with one parameter and no output schema, the description adequately conveys the key outputs (full details and script body) and a prerequisite. 'Full details' is somewhat vague, but it is sufficient for tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, sys_id, is already fully documented in the schema with 'System ID of the client script' (100% coverage). The description adds no additional parameter-level meaning, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation ('Get') and the resource ('client script'), and specifies that it returns full details and the script body. This distinguishes it from sibling tools like list_client_scripts and get_script_include.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete prerequisite (SCRIPTING_ENABLED=true), giving the agent actionable context for when the tool can be used. It does not explicitly name alternatives or exclusion cases, but the prerequisite plus resource specificity is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint=true, so the agent knows this is a safe read operation. The description adds that it returns 'full details' and accepts both formats, but doesn't describe pagination, field selection, or error behavior. This is sufficient given the read-only annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, immediately states the action and target, and provides a specific example. It contains no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple getter with one parameter and read-only annotation, the description sufficiently covers what the tool does and how to identify the record. The mention of 'full details' implies a comprehensive return, though no output schema is provided; but for this kind of tool, the information is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter with a description, but the tool description adds a concrete example (CS0001234), clarifying the expected format of the case number. This goes beyond the schema by providing a real-world pattern, which is helpful for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details of a single CSM case, using a specific verb ('Get') and resource ('CSM case'). It also specifies the identifiers accepted (number or sys_id), distinguishing it from sibling tools like list_csm_cases, which list multiple cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this when you need full details of a specific case identified by number or sys_id. It doesn't explicitly mention alternatives, but the identifier-based parameter implies it's not for browsing/searching, which is handled by sibling tools like list_csm_cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds the output fields (name and URL), but no additional behavioral details such as error conditions or side effects. It is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise, and front-loaded with the action and resource. Every word earns its place, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description sufficiently explains what it does and what it returns. It could mention potential edge cases, but for a current-instance getter, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is empty. Per the rubric, a baseline of 4 is appropriate when there are no parameters; the description cannot add parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('currently active ServiceNow instance') and explicitly states the output (name and URL). It clearly distinguishes from siblings like 'list_instances' (which lists all instances) and 'switch_instance' (which changes the active instance).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this when you need the current instance name and URL. It does not explicitly mention alternatives or exclusions, but the purpose is simple and standalone, making the usage obvious given siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds value by specifying the exact components returned (HTML, CSS, client/server scripts), setting expectations beyond the annotations. No contradiction; the description complements the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the tool's purpose and key details without redundancy. Every word earns its place; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter retrieval tool with a clear description and readOnly annotations, the description is nearly complete. It lists the output contents explicitly. Lacking an output schema, one might expect a bit more about return format, but the description covers the essential expectations for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the parameter 'id_or_sysid' fully described in the schema (e.g., 'widget-cool-clock'). The description adds no additional parameter semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and the specific resource ('full source code ... of a Service Portal widget'), distinguishing it from sibling tools like list_portal_widgets (listing widgets) or get_portal_page (page source). It enumerates what the source code includes (HTML, CSS, client/server scripts), 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage context: retrieving the full source code for a single widget. It does not explicitly mention alternatives or when-not-to-use scenarios, but the 'full source code' wording clearly differentiates from listing widgets. Clear context without explicit exclusions earns a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description 'Get' aligns with that. It adds a meaningful prerequisite (SCRIPTING_ENABLED=true) not present in annotations, and hints at output scope ('full details and conditions'). This is useful 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and includes a critical requirement in parentheses. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter and no output schema, the description adequately states what is returned ('full details and conditions') and the key prerequisite. It is complete enough for an agent to use, though more detail on output format could be added.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single parameter sys_id with description 'UI Policy sys_id'. The description does not add additional parameter meaning beyond what the schema states, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('UI Policy'), and mentions 'full details and conditions' which distinguishes it from list_ui_policies that provides a list. It clearly states 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by noting the requirement 'SCRIPTING_ENABLED=true', which is a prerequisite. It implies use for retrieving a specific policy's details rather than listing, but does not explicitly name alternatives or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds the environment requirement 'SCRIPTING_ENABLED=true', which is beyond the annotations. It also clarifies the scope of ACLs (read/write/create/delete) but does not introduce any contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that starts with the action 'List Access Control rules (ACLs)' and appends a required condition in parentheses. It contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with four optional parameters and no output schema, the description covers its purpose, the meaning of ACLs, and an important prerequisite. It does not include pagination or ordering details, but those are not essential for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all four parameters with descriptions (100% coverage), so the description adds no additional parameter-level meaning. The baseline of 3 applies; the description does not elaborate on limit, table, active, or operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the resource as 'Access Control rules (ACLs)', further clarifying with 'who can read/write/create/delete records'. This clearly distinguishes it from sibling tools like get_acl, create_acl, and update_acl.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool lists ACLs and notes a prerequisite ('requires SCRIPTING_ENABLED=true'), giving some usage guidance. However, it does not explicitly mention alternatives or when-not-to-use scenarios, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the read-only behavior is covered. The description adds value by explaining the search scope distinction (account-filtered vs global), which is not captured in annotations. This is useful 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence conveys the complete purpose without redundancy. Every word earns its place, and the two usage modes are clearly presented. This is exemplary conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list/search tool with complete schema coverage and strong annotations, the description is sufficient. It lacks explicit mention of return format, but no output schema exists and the purpose is clear. Minor gap: no explicit note that results are paginated with a default limit, though schema covers limit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described (limit, query, account_sysid). The description adds slight relational context by mapping 'for an account' to account_sysid and 'search across all contacts' to query, but the schema already carries most of the semantic weight. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists contacts and distinguishes between two modes: listing for a specific account via account_sysid or searching across all contacts via query. This is a specific verb+resource and differentiates from sibling tools like get_csm_contact (which retrieves a single contact).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when you need to list contacts for an account or search across all contacts. It does not name explicit alternatives like get_csm_contact for single-contact lookup, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the description doesn't need to restate safety. It adds the prerequisite NOW_ASSIST_ENABLED, which is a behavioral requirement not captured in the annotations, and specifies 'definitions' to clarify the return type. This goes beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential purpose and a key prerequisite without any fluff. Every word serves a purpose, and it is immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 with well-documented optional parameters and annotations indicating safety and open-world behavior, the description is adequately complete. It could optionally mention what a 'definition' includes, but given the clear name and schema, the current level is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for all three parameters (limit, query, active), so schema coverage is 100%. The description adds no additional parameter-level detail, and per the rubric, the baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with a clear resource ('Now Assist skill definitions'), making the tool's purpose immediately obvious. It also distinguishes from the sibling tools get_now_assist_skill (single retrieval) and create_now_assist_skill (creation) through the list/get/create naming pattern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite ('requires NOW_ASSIST_ENABLED'), which is useful contextual guidance for when the tool can be used. However, it does not explicitly mention alternatives or when to favor this tool over get_now_assist_skill, though the sibling list implies that distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the SCRIPTING_ENABLED=true prerequisite, which is a behavioral requirement beyond what annotations provide. Annotations already indicate a non-readonly, non-idempotent write, so the description complements rather than repeats, though it doesn't detail failure modes or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, and includes a parenthetical prerequisite. It is concise with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose and a key prerequisite. With full schema coverage and annotations, it is sufficiently complete for a simple registration tool, though it does not describe return or error behavior. Given the tool's simplicity, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 no parameter-level details beyond what the schema already documents, so no extra credit is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('register') with a clear resource ('custom event in the event registry') and a prerequisite. It distinguishes from siblings like list_event_registry, get_event_registry_entry, and fire_event by making the creation aspect explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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, noting it requires SCRIPTING_ENABLED=true. It doesn't explicitly mention alternatives or exclusions, but the purpose is clear within the event toolset, and the prerequisite serves as a usage condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's 'Delete' is consistent but not additive. It adds value by naming the WRITE_ENABLED requirement and the source of the changes array (rollback_token), which are not in annotations. There is 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, each conveying essential information: the action and a usage example, then a prerequisite. There is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive operation with a fully described schema, the description covers the action, typical source, and a key environment requirement. It does not discuss failure modes or return values, but these are not critical given the schema and annotations. It is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the 'changes' parameter as 'Array of { table, sys_id } to delete', providing full coverage. The description adds a slight hint about where to obtain this array (rollback_token) but does not add detail about the nested fields. Given the high schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Delete a set of previously-created records') with a specific resource type, and the example referencing bulk_create_records distinguishes it from the broader delete_record tool. This is a specific verb+resource definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a concrete use case (rolling back records created by bulk_create_records) and an operational prerequisite (WRITE_ENABLED=true). However, it does not explicitly contrast with alternative deletion tools or state when not to use it, though the context is otherwise clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds meaningful context: 'Read-only; uses the public docs site, not your instance' and describes the result payload (title, breadcrumb, URL, snippet, ref). It doesn't discuss failure modes or rate limits, but the key behavioral boundary (external docs vs instance) is clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: action+scope, return format+companion tool, usage guidance+safety. No redundancy; information is front-loaded and well organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with full schema coverage and read-only annotations, the description is sufficient: it specifies content domain, result fields, how to fetch full pages, and the external/public nature. It could theoretically discuss pagination or no-result handling, but the complexity is low and the description covers the key operational aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter (query, limit, product) already has a clear description. The tool description adds no additional parameter-level semantics, though it does provide useful examples of query strings in the schema. Baseline 3 is appropriate when schema fully documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Search the official ServiceNow product documentation'), lists content types (API refs, guides, encoded-query operators, release notes), and explicitly names fetch_servicenow_doc as the companion tool. This clearly distinguishes it from other search tools like search_knowledge or search_tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear when-to-use directive: 'Use this to ground answers in current ServiceNow docs rather than memory.' It also notes it's public docs, not your instance, which clarifies it's not for instance-specific lookups. However, it does not name explicit alternatives or state when not to use it beyond that.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds the WRITE_ENABLED=true prerequisite and the specific state transition to 'Requested', which is meaningful behavioral context beyond the annotations. It doesn't describe side effects post-approval, but it adds value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the action, target state, and a key prerequisite with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, the description covers the essential purpose and prerequisite. It doesn't address edge cases like what happens if the change is already in Requested state, but that level of detail is not required for such a simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter sys_id is fully documented in the schema with 'System ID of the change request'. The description adds no extra parameter semantics. With 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Move' with a clear target state ('Requested') and purpose ('for approval'), which distinguishes it from sibling tools like create_change_request, update_change_request, or close_change_request. The action and resource are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates the purpose (submitting a change for approval) and implies when it should be used, but it does not explicitly mention alternatives or when not to use it. Since the context is clear but there are no exclusions, this earns a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds a meaningful prerequisite—'requires NOW_ASSIST_ENABLED'—which is beyond what annotations provide. It also clarifies the intent (verifying behavior) but does not detail side effects or return format; however, with the readOnly hint, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action and purpose. It includes the critical environment requirement without any redundant or extra wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two well-documented parameters and a simple testing purpose, the description is fairly complete. It states what it does and a key precondition. The only gap is not explaining what the expected response contains, but this is mitigated by the simplicity and the presence of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with descriptions, achieving 100% coverage. The tool description adds no additional parameter information beyond the schema, so it meets the baseline without enhancing semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Invoke') and clearly identifies the resource ('a Now Assist skill') and the purpose ('to verify behavior'). It distinguishes from sibling tools like get_now_assist_skill or list_now_assist_skills by focusing on testing with input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys when to use the tool: when you need to test a Now Assist skill with sample input. It does not explicitly name alternatives or when-not conditions, but the context is clear enough for an agent to differentiate from retrieving or listing skills.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds the important permission requirement (WRITE_ENABLED=true), which is not captured by annotations. It does not contradict any annotation, and it clarifies the write 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that states the action, target, and a key requirement. It is front-loaded with the verb and resource, and every word contributes meaning. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only two parameters, no output schema, and annotations covering safety, the description is adequately complete. It conveys the core purpose and permission constraint. It could be slightly enhanced by noting that updates are partial (only specified fields), but that is an implied attribute of a fields-map parameter and not a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with clear descriptions for both sys_id and fields. The description adds no extra parameter details beyond restating 'update fields,' so it does not compensate beyond the schema's baseline. The nested 'fields' object lacks examples or accepted value formats, but the schema already carries the semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and precise resource ('existing CSM case'), clearly distinguishing it from siblings like create_csm_case, get_csm_case, list_csm_cases, and close_csm_case. The phrase 'existing' correctly restricts scope to updates, not creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite ('requires WRITE_ENABLED=true') and implies the tool is for modifying an existing case, not for creation or retrieval. However, it does not explicitly name alternatives or state when not to use it, such as when using the generic update_record tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the WRITE_ENABLED=true requirement beyond what annotations provide. Annotations already cover readOnly=false, destructive=false, and idempotent=true, so the additional prerequisite is valuable. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. The parenthetical is concise and adds relevant context without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update operation with two well-documented parameters and annotations providing safety profile, the description is adequate. It doesn't mention return values or failure modes, but these are not critical given the straightforward nature and complete schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both 'fields' and 'sys_id' described. The tool description adds no additional parameter meaning, so the baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'Update' and the resource 'an epic', distinguishing it from create_epic and list_epics. The parenthetical prerequisite doesn't obscure the primary purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear prerequisite (WRITE_ENABLED=true) which is useful context for when this tool can be used. It doesn't explicitly compare with alternatives like update_story, but the resource-specific nature makes the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds behavioral context by requiring WRITE_ENABLED=true, a configuration prerequisite not evident from schema or annotations. It is consistent with idempotentHint=true, as updating fields is idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that immediately states the action, target, and a key prerequisite. No filler words or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter update tool with complete schema descriptions and annotations, the description provides sufficient context: what it does and a key requirement. It does not describe return values, but there is no output schema, and the tool's simplicity reduces the need for further detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions (sys_id, fields). The description adds no extra parameter-level meaning beyond what is already in the schema, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the specific action ('Update fields') and resource ('existing incident'), distinguishing it from sibling tools like create_incident, resolve_incident, and close_incident. It also scopes the update to fields, matching the parameter schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides a clear prerequisite (WRITE_ENABLED=true) and implies usage context: when you have an existing incident's sys_id and want to modify fields. It does not explicitly mention alternatives, but the tool name and incident-specific scope make when to use it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive, idempotent operation. The description adds the WRITE_ENABLED requirement, which is valuable auth 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence with no redundancy. It front-loads the action and resource, then appends the essential permission condition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple update operation with well-documented schema and helpful annotations. The permission note is useful. No output schema exists, but absent guidance on return format is acceptable given standard update semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions. The tool description adds no parameter-specific meaning beyond the schema's key-value pair and sys_id descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool updates a PPM project (pm_project) with a specific verb-resource pair. It is easily distinguished from sibling tools like create_project and list_projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States a clear prerequisite (WRITE_ENABLED=true) for when the tool can be used. It implicitly differentiates from create/list by the word 'update' but does not explicitly mention alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the write nature is covered. The description adds meaningful context beyond annotations: the WRITE_ENABLED=true prerequisite and the dry_run preview behavior (before→after diff without writing). No contradiction with annotations, though failure modes and side effects are not disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose, then the key option. Every word earns its place – no fluff or repetition of parameter names.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic update tool with 4 documented parameters, annotations, and no output schema, the description covers the essential behavior and the important dry_run option. It lacks error conditions or return format, but these aren't necessary given the schema and annotations. A solid, adequate description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters have schema descriptions, giving 100% schema coverage. The description adds no extra parameter semantics beyond what the schema already provides; dry_run is already documented 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Update an existing record in any ServiceNow table' – a specific verb+resource+scope. It distinguishes from siblings like create_record, delete_record, get_record by focusing on updating existing records, and the open scope differentiates it from specialized update_incident, update_asset, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: this is a generic update tool for any table, requires WRITE_ENABLED=true, and offers dry_run=true for preview. It doesn't explicitly name alternatives or exclusions, but the scoping and permission note give clear context. Not a 5 because no explicit 'use this instead of X' or 'don't use when Y'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the WRITE_ENABLED=true requirement, which is not present in the annotations and is useful operational context. Annotations already indicate non-readonly (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false), and the description does not contradict these. While it doesn't disclose side effects like return values or result format, the annotation coverage lowers the burden, making this sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the core purpose immediately and appends the write-enable requirement concisely. Every word contributes value; there is no fluff or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple two-parameter update operation with full schema descriptions and clear annotations, so the description is appropriately sized. It does not mention return values or response format, but no output schema exists and for an update tool this is not a critical gap. The description, combined with schema and annotations, provides enough context for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters completely: sys_id as "Report sys_id" and fields as "Fields to update (title, type, query, field, aggregate, etc.)." The description adds no additional parameter-level meaning beyond what the schema provides. With 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: "Update an existing saved report definition," clearly indicating a mutation operation on an existing report rather than creation or read. The word "existing" distinguishes it from sibling tools like create_report and get_report. The added "requires WRITE_ENABLED=true" also hints at operational prerequisites without confusing the core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase "existing saved report definition" implies this is for modifying already-created reports, providing clear context versus create_report. It also states a precondition (WRITE_ENABLED=true), which helps the agent know when the tool can be used. It does not explicitly name alternatives or exclusions, but for this simple update, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds the specific prerequisite 'requires WRITE_ENABLED=true', which is a behavioral requirement not captured in annotations. It does not elaborate on side effects, but given the annotations, this additional context is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the verb and resource ('Update an existing scoped application') and then adds a necessary requirement. There is no redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, both documented) and the presence of annotations covering read-only/destructive behavior, the description provides adequate context: purpose and required permission. It does not mention return behavior, but no output schema exists to expect that. It could be slightly more explicit about what 'update' entails (e.g., partial update), but it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters (sys_id and fields) with descriptions, and schema coverage is 100%. The tool description does not add any additional parameter 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing scoped application' with a specific verb and resource, and adds the requirement 'requires WRITE_ENABLED=true'. This distinguishes it from read-only operations and from create_scoped_app (which creates new apps) by using 'existing'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: use this tool to update an existing scoped application and it requires WRITE_ENABLED=true. However, it does not explicitly mention alternatives or exclusions (e.g., 'use create_scoped_app for new apps'), so it lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false (write operation), destructiveHint=false, and idempotentHint=false. The description adds a valuable prerequisite: 'requires WRITE_ENABLED=true', which is authentication context not present in annotations. It does not disclose details like size limits or whether the attachment is appended vs. replaced, but the annotations cover the safety profile, so this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the primary action ('Upload a base64-encoded attachment to a ServiceNow record') and includes a necessary prerequisite in a parenthetical. There is no wasted wording or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With five required parameters and no output schema, the description explains the purpose, prerequisite, and typical use cases. It does not describe the return value or potential failure modes, but for a straightforward upload operation with complete schema and annotations, this is sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 five parameters. The tool description reinforces base64 encoding and gives examples of file types (screenshots, documents), which slightly adds meaning beyond the schema, but it does not provide substantial param-specific detail. The baseline of 3 applies because the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Upload' with a clear resource ('a base64-encoded attachment to a ServiceNow record') and distinguishes it from sibling attachment tools (list_attachments, get_attachment_metadata, delete_attachment) by being the only tool that creates/uploads. The mention of 'base64-encoded' and the target record adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context with 'Useful for adding files, screenshots, or documents to incidents, changes, etc.', which guides the agent on typical use cases. It does not explicitly name alternative tools or state when not to use it, but the family of attachment tools is clear, and the description implies this is the creation operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds that validation specifically checks for conflicts and missing dependencies, which is useful behavioral context beyond the annotations. It does not describe output format or side effects, but the read-only annotation reduces the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the action and purpose. Every word contributes to the meaning, with no redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two optional parameters, no output schema, and annotations covering safety and open-world behavior, the description provides sufficient context for understanding what the tool does. It could mention what the validation returns, but the stated checks and pre-deployment framing make it adequate for a simple validation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with clear descriptions for both parameters ('Scoped app sys_id (alternative to update set)' and 'Update set sys_id to validate'). The description simply paraphrases 'update set or app' without adding additional semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('pre-validate') with clear resources ('an update set or app') and defines the scope ('before deployment') and purpose ('check for conflicts and missing dependencies'). This distinguishes it from similar validation tools like validate_artifact, which target artifacts rather than deployment readiness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'before deployment' provides a clear usage context. However, it does not explicitly mention when not to use it or name alternatives such as preview_update_set, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description adds the behavioral guarantee 'without saving', which aligns with the read-only intent. It also clarifies that validation is against 'declared type constraints', providing context about what is checked. It does not describe failure responses, but the annotations 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that omits all redundant words. 'Validate a property value against its declared type constraints without saving' conveys purpose, scope, and side-effect behavior efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple operation with two parameters and no output schema, and the description adequately covers what it does and its non-mutating nature. It does not explain return values, but this is acceptable for a validation tool where the success/failure result is intuitive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters, so the schema already documents that 'name' is a property name and 'value' is a value to validate. The description adds 'declared type constraints' which gives context that validation uses the property's type, but does not add per-parameter details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Validate' and identifies the resource as 'property value', with the scope 'against its declared type constraints without saving'. This clearly distinguishes it from sibling tools like validate_artifact, validate_query, and validate_deployment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without saving' clearly implies the tool is intended for pre-save validation, distinguishing it from property-setting tools like set_system_property or bulk_set_properties. However, it does not explicitly name alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, non-destructive write operation. The description adds the key prerequisite of WRITE_ENABLED=true, which is valuable context beyond what annotations provide. This is a meaningful behavioral constraint for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words. The verb and resource are front-loaded, and the requirement is a parenthetical addition that doesn't clutter the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with comprehensive schema descriptions and annotations, this description provides the essential context: what it does and a required permission. No output schema exists, so return value details aren't expected. The description is complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive comments for all 4 parameters. The description doesn't add param-specific details, but with full schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new Performance Analytics dashboard', specifying the action, resource, and domain. It distinguishes itself from sibling tools like update_dashboard and list_pa_dashboards, and the parenthetical requirement adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for use (creating dashboards) and includes a prerequisite (WRITE_ENABLED=true). However, it does not explicitly name alternatives or state when not to use it, but the context is strong enough for a create tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds value by stating the WRITE_ENABLED=true requirement, which is a useful operational prerequisite 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences that immediately state the action, target, and required setting. Every word earns its place, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, strong annotations), the description fully covers the action, the required identifier, and the authorization prerequisite. It is complete and self-sufficient for a straightforward delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—the schema fully describes the sys_id parameter as 'The m2m_story_dependencies record sys_id'. The description mentions the same identifier but adds no additional semantic detail beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove'), names the exact resource ('story dependency link'), and specifies the identifier type ('m2m_story_dependencies sys_id'). This clearly distinguishes it from related tools like create_story_dependency and list_story_dependencies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for use—removing a dependency by its sys_id—and the explicit prerequisite 'Requires WRITE_ENABLED=true' helps the agent know when the call will work. It does not explicitly contrast with alternatives, but the purpose is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds valuable behavioral context by specifying the exact command ('npx @servicenow/sdk explain <topic>'), emphasizing 'always current API signatures, not training-data guesses', and describing the response as explanations of Fluent APIs, types, and patterns—this goes beyond what annotations state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the command and purpose, then explains the output, then lists supported topics. While the topic list is long, it is structured as a single sentence and serves a practical purpose (enumerating valid inputs). No redundant words, though the list could arguably be shortened without losing intent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one parameter, no output schema, and annotations covering safety, the description adequately covers purpose, usage, and examples. It states what the tool returns ('explanations of Fluent APIs, types, patterns, and best practices') but does not specify the response format (e.g., plain text, structured JSON). This is a minor gap, but the description is otherwise complete enough for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the 'topic' parameter with examples, and schema coverage is 100%. The description enriches this with a much longer list of acceptable topics (GlideQuery, table API, scoped app, etc.) and clarifies the scope (Fluent APIs, types, patterns, best practices), adding meaning beyond the schema's brief description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs `npx @servicenow/sdk explain <topic>` to provide live SDK documentation, with a specific verb ('explain') and resource (SDK topics). It distinguishes itself from sibling tools by focusing on Fluent SDK topics and the explain command, not generic documentation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys when to use it (when live API signatures or explanations of Fluent APIs, types, patterns, and best practices are needed) and lists many valid topics. However, it does not explicitly mention alternative tools or exclusion criteria, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds context about a required setting (SCRIPTING_ENABLED=true) and specifies what information will be returned, which goes beyond the structured data. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the action and specific details, with the prerequisite in parentheses. No redundant or unnecessary words are used.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-only tool, the description covers the purpose, the specific details returned, and an operational requirement. Without an output schema, it still gives the agent enough context about what to expect. The openWorldHint annotation is not contradicted and the description is appropriately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage of the single 'sys_id' parameter, describing it as 'ACL sys_id.' The description does not add additional semantic detail about the parameter, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and clearly identifies the resource as 'an ACL rule,' with the scope 'full details including its script and role requirements.' This distinguishes it from sibling tools like list_acls, create_acl, and update_acl.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing detailed information about a specific ACL, especially the script and role requirements, and notes a key prerequisite (SCRIPTING_ENABLED=true). However, it does not explicitly mention alternatives or exclusion criteria, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a benign read. The description adds the 'currently active' and 'session' context, but does not describe return format or potential nuances. It adds some value beyond annotations but not enough to exceed the baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that immediately states the action and resource with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple parameterless getter with strong annotations. The description is sufficient for an agent to invoke it correctly; no output schema is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and the schema is empty, so the description has no parameter burden. The baseline for zero params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and clearly identifies the resource as the 'currently active Update Set' scoped to 'the session', distinguishing it from sibling tools like list_update_sets and switch_update_set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this is for retrieving the session's active Update Set, which is distinct from listing, switching, or ensuring active. However, it does not explicitly name alternatives or provide when-not-to-use guidance, so it falls just short of full explicitness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds a valuable behavioral constraint: the Copilot topic mapping is configured in Copilot Studio and not available via ServiceNow REST. This goes beyond annotations and prevents the agent from expecting mapping data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and every sentence adds value. The second sentence clarifies an important limitation without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity list tool with one optional parameter, good annotations, and no output schema, the description is sufficiently complete. It states what is returned, scopes the results, and explicitly notes the external mapping limitation, leaving no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the single parameter (limit) with a clear description. The tool description adds no additional parameter detail, so the baseline of 3 applies per the rubric.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Virtual Agent topics (sys_cs_topic) that back a Microsoft Copilot integration. This specific verb+resource+scope distinguishes it from siblings like list_va_topics_full, and the additional context about Copilot Studio mapping clarifies the tool's focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when interested in topics backing a Copilot integration, not just any VA topics. It also notes that the mapping itself is not exposed via ServiceNow REST, setting expectations. However, it does not explicitly name alternatives or provide when-not-to-use guidance, so no 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds the qualifier 'available' and clarifies model types, but does not describe return format, pagination, or other behavioral details, which is fine given 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words. It efficiently conveys the tool's scope and purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter listing tool with read-only annotations, the description fully covers what an agent needs: it names the resource type, specifies the domain, and implies the output is a list. No output schema exists, but the description gives enough context to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantic burden. The description provides all necessary context about what will be returned, making the empty schema fully sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists available Predictive Intelligence solutions, specifying the resource (PI models) and clarifying what these are (classification/similarity models). This distinguishes it from other list tools and ML training/evaluation tools in the sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The style is a straightforward list command with clear context: use this tool to see what PI models are available. There are no explicit exclusions or alternative tool references, but the uniqueness of the purpose makes the usage implied enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only, lowering the bar. The description adds useful behavioral context by explaining where scoped logs land (syslog_app_scope) and how gs.info()/gs.log() output is routed. It doesn't discuss return format or pagination, but with annotations covering 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear, front-loaded sentences. The first states the purpose; the second clarifies the key parameter nuance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only log retrieval tool with good schema coverage and no output schema, the description sufficiently covers purpose and the only notable behavioral nuance (app_scope). It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all three parameters having descriptions, so the baseline is 3. The description reinforces the app_scope behavior but doesn't add new syntax or meaning beyond what the schema already provides for limit and query.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves system log entries for debugging or auditing, with a specific verb and resource. It also distinguishes between scoped and global logs, which differentiates it from any potential log-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance on when to use the app_scope parameter to read scoped-application logs instead of the global syslog. However, it doesn't explicitly mention when not to use this tool or what alternatives exist, so it falls short of full exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds the environment dependency (SCRIPTING_ENABLED=true), which is valuable context beyond the annotations. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that conveys both the purpose and a key requirement without any redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter, the description provides the essential purpose, the return scope ('full details and script'), and a critical prerequisite. Annotations cover safety and openness. No output schema is present, but the description adequately sets expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of 'sys_id' as 'UI Action sys_id'. The tool description does not add further parameter-specific meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('UI Action'), and specifies it returns 'full details and script'. This clearly distinguishes it from sibling tools like list_ui_actions (which lists) and create/update_ui_action (which mutate).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite: 'requires SCRIPTING_ENABLED=true', which tells the agent when this tool is applicable. It implies this is the tool to use for retrieving full details, though it does not explicitly contrast it with list_ui_actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context: each lane returns {count, records} or {error} if the table/plugin is unavailable. This goes beyond the annotations without contradicting them, though it doesn't cover limit-related behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, front-loaded with the core function, then use case, then scope/return format. No wasted words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains return shape ({count, records} or {error}) and explicitly distinguishes config/metadata impact from CMDB CI impact. The tool's complexity (multiple artifact types) is adequately covered 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (table, limit). The description does not add meaning beyond the schema, e.g., it doesn't mention the default limit or how limit interacts with per-type counts. Baseline 3 is appropriate since schema already carries the parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Uses a specific verb+resource+scope ('List every configuration artifact on a table') and enumerates the artifact types (business rules, client scripts, UI policies, ACLs, etc.) with per-type counts. This clearly distinguishes it from sibling tools that list individual artifact types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use guidance: 'Use it to see what depends on a table before changing or removing it.' It also clarifies a key exclusion ('not CMDB CI impact'), but does not explicitly name an alternative tool for CMDB impact. Thus it stops short of full when/when-not/alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state readOnlyHint=true; the description adds behavioral detail by listing what is validated (javascript: expressions, allowlist, length limits, common mistakes) and the return shape. This goes beyond the annotation baseline, though it does not disclose all potential edge cases or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly-written sentence that front-loads the main action, includes concrete examples of validation checks, and states the return value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, clear annotations), the description covers purpose, usage timing, return format, and validation specifics. It is fully sufficient for an agent to select and invoke the tool correctly without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a good example and description for the 'query' parameter. The tool description adds some context about common mistakes but does not significantly expand parameter semantics beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Lint-check' and identifies the resource as 'ServiceNow encoded query', with the scope 'BEFORE running it'. It clearly distinguishes from siblings like query_records or fluent_query by emphasizing validation rather than execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool ('BEFORE running it'), implying a pre-execution validation step. However, it does not mention alternatives or exclusions, such as 'use query_records for actual execution', so it lacks explicit comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behaviors beyond annotations: it returns a rollback_token, tracks all created sys_ids, deletes already-created records on mid-way failure when rollback_on_error=true, supports dry_run, and requires WRITE_ENABLED=true. These are not captured in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the primary action. No wasted words; covers purpose, rollback semantics, and prerequisites efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description mentions the key return elements (created sys_ids and rollback_token) and covers essential behaviors. Missing details like exact response structure or batch size limits, but overall sufficient for a bulk create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds minimal parameter-specific meaning beyond restating the behaviors of rollback_on_error and dry_run. The schema already describes each parameter, so the description does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: bulk-creating records in a single table, distinguishing it from single-record create tools like create_record. It also mentions key outputs (sys_id tracking, rollback_token) and features (dry_run).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Create many records in one table in a single call' implies when to use this over single-record tools. It also specifies a prerequisite (WRITE_ENABLED=true) and describes rollback behavior when rollback_on_error is set, but doesn't explicitly name alternative tools for single-record creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and openWorldHint. The description adds that only ServiceNow docs are reachable, that the ref is fastest/exact, and that it fetches 'full readable text'. This goes beyond the annotations but does not cover behavior like rate limits or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four short sentences, each earning its place. It is front-loaded with the main purpose, then provides input guidance, usage context, and scope constraint. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what, how, when, and constraints. Since there is no output schema, it does not explicitly state the return format beyond 'full readable text', and it doesn't mention maxChars behavior (though that is in the schema). Still, it is largely complete for a simple read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains all three parameters. The description reiterates the ref/URL distinction and adds 'fastest, exact' as extra context, but that is marginal beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Fetch the full readable text of a specific ServiceNow documentation page' – a specific verb+resource+scope. It clearly distinguishes itself from the sibling search_servicenow_docs by positioning itself as the follow-up action to read a result in full.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use after search_servicenow_docs to read a result in full', naming the alternative and the proper sequence. It also gives guidance on which parameter to use (ref preferred, URL fallback) and restricts the scope: 'only ServiceNow docs are reachable'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral detail: script matching is substring-based (LIKE), results may have false positives, and dynamically-built references can be missed. It also frames the output as 'candidates to review' rather than a definitive list, which is beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, each with a distinct purpose: state the function, state the use case, and disclose limitations. It is front-loaded with the core purpose and contains no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining the result shape, and it does convey that results include dictionary entries and script hits. However, it does not specify the exact structure of the response or how the 'limit' parameter affects results, leaving some ambiguity for an agent invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% parameter descriptions, so the description adds limited parameter-level detail. The context that script matches are substring hits informs how the 'field' parameter is used, but this is more behavioral than semantic. A baseline of 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource structure—'Find where a table field is used'—and enumerates the scope (dictionary entry, scripts) clearly. It distinguishes itself from sibling find tools like find_script_references by focusing on fields and including dictionary metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('before renaming or removing a field') and provides caveats about false positives and misses. However, it does not explicitly mention alternative tools or when not to use it, so it stops short of full exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral details beyond the readOnlyHint and openWorldHint annotations: it uses keyword-based matching, returns only resolved incidents, and ranks them by keyword match count. This gives the agent a clearer picture of expected results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise—two sentences—and front-loaded with the main action, followed by input specifics and output behavior. 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.
Completeness4/5
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 adequately covers what the tool does, how inputs relate, and what the output looks like. It does not mention edge cases like both inputs provided, but overall it is complete enough for an agent to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds important semantic insight by clarifying that incident_sys_id and short_description are alternative inputs (one or the other should be provided), which the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: finding similar past incidents using keyword-based matching. It specifies the input types (sys_id or short_description) and the output (resolved incidents ranked by keyword match count), which distinguishes it from other ML tool siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by explaining the two mutually exclusive input modes: incident_sys_id for finding similar incidents, and short_description for free-text matching. It does not explicitly exclude alternatives or mention when not to use, but the guidance is sufficient for most cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 field-level status semantics and the sys_updated_on output's purpose, going beyond the annotation baseline with useful behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with 'Local sync: compare...'. Every sentence adds meaning with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but the description outlines return semantics (field statuses and sys_updated_on). The input schema is fully documented. It misses detailed formatting of the output, but for a compare tool this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameter descriptions exist. The description adds value by explaining that 'fields' defaults to files under NOWAIKIT_SYNC_DIR, and clarifies the purpose of sys_updated_on, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool does a field-by-field comparison between an artifact's instance content and local/edited content, with specific status outputs (unchanged, changed, not_local). It also connects to push_artifact's conflict check, distinguishing it from sibling tools like compare_instances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: it's a local sync comparison step that feeds into push_artifact's conflict check. It does not explicitly name alternatives or exclusions, but the purpose and connection to push_artifact give clear practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds rich behavioral context beyond the readOnlyHint annotation: it explains the substring/LIKE search nature, warns about false positives from comments/similar names, and notes misses for dynamic references. This gives agents important expectations about result reliability and interpretation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core purpose, followed by usage context and behavioral caveats. Every sentence adds value with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, strong annotations (readOnlyHint), and complete schema, the description covers all essential aspects: what it does, when to use it, how to interpret results, and its limitations. No output schema is needed for a search/reference tool, and the description is sufficient for an agent to invoke and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 (100% coverage). The description reinforces the meaning of 'name' with an example but does not add significant additional semantics 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb ('Find') and resource ('references to a Script Include or named artifact'), and specifies the scanning mechanism ('script-bearing config tables for textual use of the name'). This distinguishes it from sibling tools like find_field_references or find_artifact by focusing on script includes and named artifacts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Use it before renaming or deleting a Script Include, Script Action, etc.' It also explains the substring matching behavior and caveats (false positives, dynamic reference misses), but does not mention alternatives or when-not-to-use, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare `readOnlyHint: true` and `openWorldHint: true`, and the description reinforces the read-only nature with "read-only" and adds useful context that the command runs via the CLI against the authenticated instance with "no browser." It also mentions that the feature is new in @servicenow/sdk 4.8, adding version awareness. However, it does not disclose potential prerequisites like needing the SDK installed, but this is beyond what annotations provide, so it adds solid value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the command and its core nature, then adds version and use-case context, and ends with a compact example. Every sentence contributes useful information without redundancy, and the structure flows logically from what to how to when.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only query tool with complete schema coverage and no output schema, the description is well-rounded: it explains what the tool does, how it executes (CLI), when to use it, and provides an example. It does not need to detail return values because the tool is a straightforward query execution, and the annotations cover side-effect safety. This makes it complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all four parameters with 100% coverage, providing baseline 3. The description goes beyond by including a concrete example (`{ table: "sys_user_role", query: "name=admin", fields: ["sys_id","name"], limit: 1 }`) that demonstrates how all parameters work together, making the semantics clearer without repetition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a read-only Table REST API query via the ServiceNow SDK CLI, naming the exact command (`now-sdk query <table>`) and distinguishing it as a CLI-based operation with no browser. It also narrows the target use case to authoring Fluent code, listing specific purposes like resolving sys_ids and inspecting schemas, which differentiates it from generic query tools like `query_records` or `fluent_query`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 the tool: "Ideal while authoring Fluent code" and enumerates specific scenarios (resolve sys_ids, inspect table schemas, check existing records, read choice values). It does not explicitly name alternatives or state when not to use it, but the context is sufficiently clear, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 specific behavioral context: it reports the version, indicates whether it meets the tracked version, and returns an upgrade hint when outdated. No contradiction with annotations, and the added detail is useful for understanding what the tool does beyond a simple read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The main purpose is front-loaded, and the second sentence adds a key behavior (upgrade hint) without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with no output schema, the description completely covers what the tool does, what it checks, and what it returns. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema shows zero parameters, so the baseline is 4. The description doesn't need to explain parameter semantics because there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Report' and specifies the resource (installed @servicenow/sdk version) and its purpose (version compatibility check against NowAIKit's tracked version). This clearly distinguishes it from sibling tools, which are all about data operations or automation, not SDK version introspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: to check if the installed SDK meets the version NowAIKit tracks features against, and it mentions the upgrade hint for out-of-date versions. It doesn't explicitly exclude alternatives, but none exist among siblings, and the context is clear enough for an agent to select it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds valuable context about scoping vs. environment-wide listing, which implies potential large result sets and why scoping is recommended, going beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and resource, and every word adds value. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description combined with the schema covers the essential behavior: what it lists, how to scope it, and the available filters. No output schema is present, but return format is not critical for a list operation. The description is complete for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds extra meaning by explicitly recommending flow_id and explaining its effect on scope, which provides guidance not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'Flow Designer action instances'. It also differentiates from siblings like list_flows and list_flow_executions by focusing on action instances, and mentions the scoping behavior with flow_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 the flow_id parameter ('Pass flow_id to scope to a single flow's steps (recommended)') and explains the default behavior ('otherwise lists across the environment'). It doesn't explicitly mention alternatives or exclusions, but the recommendation is useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint=true annotation by describing a read-only listing operation. It goes beyond the annotation by specifying the output scope: artifact types and which fields sync for each, adding useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the domain context 'Local sync:' and packs both the action (list) and the key details (artifact types, pull/push support, field sync info). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool, the description sufficiently explains the scope and expected output. It tells the user exactly what will be listed (supported artifact types) and what detail is provided (fields synced). The openWorldHint is not contradicted and the lack of an output schema is compensated by the clear description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing to explain. The schema is empty and fully covers the input side, making the description irrelevant to parameter semantics. Baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'list' and clearly identifies the resource: 'artifact types (tables) that support pull/push to local files'. This distinguishes it from sibling tools like pull_artifact and push_artifact which perform the actual sync operations, and from sync_status which reports sync state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Local sync:' prefix provides a clear domain context, indicating this tool is for discovering supported artifact types for local sync. However, it does not explicitly mention alternatives or when not to use it, though the contrast with sync-performing siblings is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though readOnlyHint=true is annotated, the description goes beyond by explaining that it returns content inline and, when NOWAIKIT_SYNC_DIR is set, writes one file per field and returns the paths. This local write side effect is important behavioral context that annotations alone don't provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (two sentences) and front-loaded with the primary purpose ('Local sync'). Each clause adds essential information: the action, the inline return, the optional file writing behavior, and the scope distinction from export.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the two required parameters and strong schema coverage, the description sufficiently explains the tool's behavior, including return format and conditional file output. It also clarifies the single-artifact scope relative to exports, covering the primary context needed for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides thorough descriptions for both parameters (table and sys_id, including resolution of names to sys_ids), so the description adds only a concrete example (widget fields) rather than new parameter semantics. With 100% schema coverage, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches an artifact's editable fields for local editing, using specific verbs and resource types (e.g., Service Portal widget's template/css/script). It distinguishes itself from update-set export, making its purpose distinct from similar sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It opens with 'Local sync', providing context for when this tool is appropriate, and explicitly contrasts with update-set export. However, it does not name alternative tools like get_portal_widget or get_script_include, so some guidance on choosing among siblings is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint and openWorldHint, so the description doesn't need to restate safety. It adds behavioral context by explaining it returns 'matching tool names + descriptions ranked by relevance' and operates 'without loading every definition', which is useful and not redundant 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: the first states the main function, the second gives return details, and the third provides use-case context. No fluff, every sentence adds value, 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description fully covers purpose, usage, return contents, and context. The absence of an output schema is compensated by the explicit description of what is returned. Even with a large sibling list, this tool's role is clear and self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already provides clear descriptions for 'query' and 'limit'. The description reinforces the keyword search nature but doesn't add significantly beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Search'), resource ('full NowAIKit tool catalog'), and outcome ('discover the right tool'). It distinguishes itself from sibling tools by being a meta-search tool rather than a domain-specific operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to 'Use this FIRST when you are unsure which tool to call' and mentions the specific benefit with MCP_TOOL_DISCOVERY=lean. This provides clear when-to-use guidance and differentiates it from direct task tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses that matches are substring (LIKE) hits and are candidates to review, not definitive, which is valuable context beyond the readOnlyHint annotation. It also mentions that the property record itself is included, adding behavioral depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main action, followed by usage advice and a caveat. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the annotations, the description covers the essentials: purpose, usage timing, and matching limitations. It could detail the return structure since there is no output schema, but the description's hints are sufficient for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds that matching is substring-based, clarifying the 'name' parameter behavior beyond the schema's simple 'System property name, e.g....'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds scripts that read a system property by name plus the property record itself. It uses a specific verb ('Find') and names the exact resource, distinguishing it from property getters and general script reference tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use it before changing or removing a property, providing a clear context. It does not name alternative tools or when not to use it, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses significant behavior beyond the readOnlyHint and openWorldHint annotations: no 1000-row truncation, automatic average resolution time for task tables, pre-formatted duration fields, and a detailed return structure. This gives the agent a strong sense of what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: purpose, key differentiator, usage example, special behavior, output format, and read-only status. It is dense but not verbose, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and no output schema, the description explains the return components (stats table, rows, chart, summary) and critical edge cases. It covers the main use case, performance characteristics, and automatic behaviors, making it complete for agent selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds valuable semantic context for avg_fields/sum_fields (e.g., task tables auto-include average resolution time, duration fields come pre-formatted), which helps the agent use these parameters effectively without repeating schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool as a server-side aggregate report that groups by a field and returns per-group counts plus aggregates in a single query. It explicitly distinguishes from raw record listing ('Do NOT list raw records for this') and uses a specific verb+resource structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear guidance on when to use this tool ('the right tool for a periodic summary') and explicitly warns against using it for raw records. However, it does not name specific alternative tools, so it lacks the 'alternatives' component for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations indicating readOnlyHint and openWorldHint, the description adds crucial behavioral context: it registers new tools (side effect), caches schemas for 30 minutes, and states what tools become available. This is transparent about the tool's side effects and temporal behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with only three sentences. It front-loads the core purpose, lists the generated tools for clarity, and mentions the cache duration without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and side effects, the description is well-rounded: it covers what the tool does, the resulting tools, the operations filter, and the caching behavior. It doesn't need to explain return values because there is no output schema, but the description sufficiently explains the tool's effect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with descriptions for both 'table' and 'operations'. The description adds purpose by explaining that 'operations' controls which dynamic tools are enabled and that the default is all. The schema alone doesn't convey the side effect of tool registration, so the description adds value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: discovering a ServiceNow table schema and registering dynamic CRUD tools for it. It also distinguishes itself by listing the exact tools that become available and mentioning the 30-minute cache.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool by noting that it registers dynamic tools, but it doesn't explicitly contrast with alternatives like get_table_schema or query_records. It lacks an explicit 'use this instead of X' statement, but the context of creating new dynamic tools is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description discloses critical behavioral risks: writing action-instance rows over REST does not recompile the flow, leading to desync/corruption. This adds significant context that annotations cannot convey, making the tool's safety profile very transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: purpose, the critical warning, and the guidance to edit steps in the UI. Every sentence carries essential information with no fluff, and the purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a metadata update tool with full schema coverage and no output schema, the description is complete: it explains the scope, the caveat about step editing, the write nature, and the underlying reason (compiled snapshot). The annotations cover idempotency and non-destructive behavior, so no critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having a basic description (e.g., 'New name', 'Activate (true) or deactivate (false)'). The description reinforces that these are metadata fields (activate/deactivate, name, description, run-as) but does not add deeper semantic detail beyond the schema. This matches the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates flow or subflow METADATA only, listing specific fields (activate/deactivate, name, description, run-as). It distinguishes itself from step editing and clearly scopes the operation to metadata, which differentiates it from create_flow and get_flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when NOT to use this tool for editing steps, and provides the alternative: 'Edit steps in the Flow Designer UI.' It also makes clear that it is for metadata updates only, giving unambiguous usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![servicenow-mcp MCP server](https://glama.ai/mcp/servers/aartiq/servicenow-mcp/badges/card.svg)](https://glama.ai/mcp/servers/aartiq/servicenow-mcp)

Score Badge

Copy to your README.md:

[![servicenow-mcp MCP server](https://glama.ai/mcp/servers/aartiq/servicenow-mcp/badges/score.svg)](https://glama.ai/mcp/servers/aartiq/servicenow-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/aartiq/servicenow-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server