NowAIKit
Server Quality Checklist
Latest release: v4.9.0
- Disambiguation3/5
While most tools target distinct objects (e.g., create_incident vs. create_change_request), there is notable overlap among search/query tools (ai_search, natural_language_search, nlq_query, search_knowledge, etc.) and between generic query_records and fluent queries. This creates ambiguity for an agent in selecting the right tool.
Naming Consistency5/5All tool names follow a strict verb_noun pattern in snake_case (e.g., get_incident, create_acl, bulk_set_properties). Even specialized tools like fluent_build and fluent_explain adhere to this. No mixed conventions or irregular naming.
Tool Count1/5With 405 tools, the set is far beyond what is manageable for an MCP server. This extreme count overwhelms agents and violates the principle of a well-scoped tool surface. Most servers should have 3-15 tools; even 25+ is considered heavy. 405 is excessive.
Completeness5/5The tool set covers virtually every ServiceNow module (ITSM, HR, CSM, CMDB, Security, PA, Portal, UI Builder, etc.) with full CRUD operations plus specialized actions and meta-tools. There are no major gaps for the intended domain of ServiceNow automation.
Average 3.6/5 across 365 of 405 tools scored. Lowest: 2.1/5.
See the Tool Scores section below for per-tool breakdowns.
- 8 of 8 community issues answered or closed in the last 6 months
- 75 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
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.
Add related servers to improve discoverability.
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 indicate readOnlyHint=true and openWorldHint=true. The description adds minimal behavioral context; 'monitor' suggests dynamic data but does not elaborate on pagination, rate limits, or result volatility beyond what annotations cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two words beyond the tool name), but it is under-specified rather than concise. It sacrifices clarity for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and only two optional parameters, the description fails to explain what constitutes an 'active event', how to interpret results, or how to effectively use filters. This is inadequate for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema adequately defines parameters. The description adds no additional meaning about limit or query, but baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The phrase 'Monitor critical infrastructure events' is vague. 'Monitor' implies ongoing observation, but the tool name 'list_active_events' suggests a one-time list retrieval. It does not clearly state that it returns a list of active events, nor does it distinguish from sibling 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/5Does 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 alternative list tools (e.g., list_active_slas, list_event_registry). There is no mention of context, prerequisites, or exclusion criteria.
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 '[Write]', which is redundant given annotations (readOnlyHint=false). It fails to disclose other behaviors like auth requirements, rate limits, or side effects beyond what annotations 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Although short, the description is overly terse and omits essential information. It is not effectively structured to aid agent understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no output schema, and a brief description, the tool lacks critical context. The agent cannot infer return values, expected behavior, or full usage scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (only sys_id described). The description does not add any meaning to the parameters (path, title, layout), leaving the agent to guess their types or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update') and resource ('UI Builder page'), distinguishing it from related tools like create_uib_page and delete_uib_page. However, it is very brief and lacks additional 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/5Does 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 (e.g., create_uib_page or update_record). The description does not mention prerequisites or 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?
Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds no behavioral context beyond what is in the annotations, such as pagination behavior, default limit, or whether the list includes all agent definitions or only those accessible to the user.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is 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 omits important details, but conciseness is about efficiency; the description is efficient but at the cost of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of sibling tools (many list tools) and the absence of an output schema, the description is incomplete. It does not mention default limit, ordering, pagination, or what fields are returned. The openWorldHint annotation suggests variability, but the description provides no guidance on expected output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions for both parameters (limit and active). The description does not add any additional meaning or context to these parameters, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List AI agent definitions' clearly states the verb and resource, but it does not differentiate from the numerous sibling list tools. It lacks specificity about the scope (e.g., all agents, active agents) and does not add value beyond 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/5Does 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. Many list tools exist, but the description provides no context on prerequisites, filtering options, or when a different tool might be more appropriate.
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 states 'Execute a flow in test mode with sample inputs,' which implies mutation (write operation), but annotations declare readOnlyHint=true and openWorldHint=true. This is a direct contradiction. Additionally, no behavioral context (e.g., side effects, state changes) is disclosed beyond the conflicting signals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise, but it includes a stray '[Write]' marker that reduces clarity. The information density is low, and it could be more structured to convey important context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fails to explain what the tool returns, whether it runs synchronously or asynchronously, or any behavioral outcomes. Given the lack of an output schema and the tool's complexity (parameters including an object), the description is incomplete for an AI agent to safely invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the parameters are already documented. The description only adds the phrase 'sample inputs' which aligns with the test_inputs parameter, but does not provide additional semantic value or constraints beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Execute), resource (a flow), and mode (test mode with sample inputs). It is specific enough to convey the basic purpose, though it does not explicitly distinguish from sibling tools like trigger_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/5Does 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 not to use it, or how it differs from similar tools like trigger_flow or publish_flow.
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 indicate it's a write operation (readOnlyHint=false) and not destructive (destructiveHint=false), but the description adds nothing beyond stating it creates a config. No mention of side effects, required permissions, or what happens if a config with the same name exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two sentences including '[Write]' tag), which is concise but lacks structure. It could benefit from a brief note about usage or return values without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 indicate what the tool returns (e.g., the created config ID or success message). It also doesn't clarify that the 'description' parameter is optional or provide any context about mobile app configurations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% with two parameters described ('name' and 'branding_color'). The description adds no extra meaning to parameters, but the schema already provides basic descriptions. Baseline of 3 is appropriate for medium coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new mobile app configuration', which is a specific verb+resource. The name distinguishes it from sibling tools like create_mobile_applet or create_mobile_layout, so purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, nor any prerequisites or exclusions. It simply states the action without 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. The description adds no behavioral context beyond the implied read-only nature, missing details like pagination or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (4 words) with no wasted text. However, it may be too brief to be maximally useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity and annotations providing read-only context, the description fails to explain the optional 'limit' parameter or what constitutes a 'mobile layout configuration', leaving gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage for the 'limit' parameter is 0% (no description in schema), and the description does not explain the parameter's purpose, leaving its functionality ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List mobile layout configurations' uses a specific verb ('list') and resource ('mobile layout configurations'), clearly distinguishing it from sibling tools like 'create_mobile_layout' 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 Guidelines2/5Does 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 filtering by other criteria or differences from similar list 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?
Annotations already provide readOnlyHint=true and openWorldHint=true. The description adds no extra behavioral context, such as pagination behavior, query format expectations, or performance considerations. It merely restates the search action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but extremely brief. It earns its place by stating the core purpose, but lacks any additional structure or detail that could aid an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is present, and the description does not explain what a successful response contains (e.g., list of CIs with fields). Given the tool's search nature and two parameters, the description is incomplete for an agent to fully understand usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage for both parameters (limit and query). The description does not add meaning beyond what the schema already provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (search), resource (configuration items), and context (CMDB). It is a specific verb+resource combination, but does not explicitly differentiate from sibling tools like get_cmdb_ci or cmdb_find_duplicates, though 'search' implies a broader query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 get_cmdb_ci for single CI retrieval or cmdb_find_duplicates for duplicate detection. The description lacks any context for 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?
Annotations already indicate the tool is not read-only and safe to retry (idempotent). The description adds only the [Scripting] tag, implying a scripting context but not elaborating on permissions or side effects. 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very short, but at the cost of omitting important details. Could be structured to include key points like updatable fields or return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool, the description is incomplete. It does not specify return value, permissions, or constraints on input values. No output schema exists, so description should cover that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (sys_id described). The description does not clarify the meaning of 'label' or 'description' beyond their names. For low schema coverage, the description should compensate but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly specifies the verb 'update' and resource 'UI Builder component'. The [Scripting] tag adds context but doesn't distinguish from siblings like update_uib_page. However, the resource type is specific enough to avoid 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/5Does 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 create_uib_component or list_uib_components. No prerequisites or context provided for effective 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 convey read-only, idempotent, and destructive hints. The description only adds '[Write]', which is redundant given 'update' in the name and readOnlyHint=false. It does not explain partial update behavior, field effects, 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence plus marker) but lacks valuable content. While not verbose, it omits important details that would improve clarity. The '[Write]' marker is unnecessary given annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 fails to mention return value or behavior when fields are omitted. It does not clarify that the topic must exist (versus creating). Given the complexity of the 'fields' object, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds no extra meaning beyond what the schema provides ('Fields to update (name, description, active, etc.)' is already in the schema). Baseline for high coverage is 3, and no additional value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and resource (Virtual Agent topic properties), making the purpose understandable. However, it does not distinguish from sibling update tools like 'update_record' or 'update_va_topic' (though the name helps). The '[Write]' marker adds no additional clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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_va_topic' or 'get_va_topic'. There is no mention of prerequisites, when not to use it, or related 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?
Annotations indicate non-readOnly and non-idempotent behavior, but the description adds only the '[Scripting]' context. It does not disclose any additional behavioral traits such as permissions required, side effects (e.g., impact on original artifact), or error conditions. With annotations present, the bar is lower, but the description provides minimal 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of one short sentence and a tag. It is front-loaded and free of fluff. However, it might be overly brief, missing some context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite good annotations and schema coverage, the description is inadequate for a tool with 4 parameters and no output schema. It does not explain what constitutes a 'platform artifact', expected return value, or any usage constraints. The complexity of the tool warrants more detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description does not provide any additional meaning beyond what the schema already conveys. It does not explain parameter relationships or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Clone') and resource ('platform artifact'), and mentions the key features ('new name/scope'). It is specific enough to distinguish it from other tools, but does not explicitly differentiate from any potential clone alternatives among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not specify when to use this tool instead of alternatives, nor does it give context about prerequisites or scenarios where it is appropriate. The '[Scripting]' tag implies a context but 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 behavioral details beyond the obvious, such as performance implications, table limits, or output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence. It is efficient and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 specify the format or structure of the comparison results. For a data analysis tool, this omission leaves the agent with incomplete context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter schema coverage is 100% (both parameters have descriptions). The description adds marginal value; 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/5Does 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 tables, with a note about time periods and capacity planning. The verb 'compare' and resource 'record counts' are specific, but the mention of time periods is not reflected in the schema, creating 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/5Does 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_table_record_count or run_aggregate_query. There is no exclusion criteria or 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?
The annotation 'readOnlyHint: false' implies a write operation, which is redundant with the description's '[Write]'. No additional behavioral details are provided, such as required permissions, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. Every word adds value, and the structure is front-loaded with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 10 parameters and no output schema, the description provides minimal context. It lacks information on required prerequisites, auto-generated fields, or relationships, leaving gaps in understanding the tool's full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 10 parameters with descriptions, so the description adds no extra parameter meaning beyond the schema. Baseline 3 is appropriate as the schema carries the information load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 'IT asset record', which aligns with the tool's purpose. It differentiates from other 'create' siblings by specifying 'asset', though it could be more precise about 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 Guidelines2/5Does 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 when to use 'create_asset' over 'create_incident' or 'create_record'. There are no explicit when-to-use or when-not-to-use instructions.
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?
Description adds no behavioral context beyond annotations. Annotations already indicate non-read-only, non-idempotent, not destructive, but description offers no additional insights on side effects or 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and concise. Each word is necessary, though the '[Scripting]' tag is somewhat redundant given the script parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a creation tool. It does not explain what the action is used for, any constraints, or what the result is. No output schema exists to compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes parameters. The description does not add parameter meaning, but baseline for high coverage is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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, which is specific. However, it does not differentiate from sibling tools like create_flow or create_subflow beyond the 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/5Does 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. No prerequisites or context 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?
Annotations already provide readOnlyHint=false and destructiveHint=false, so the description adds minimal value by including '[Write]', which is redundant. It does not disclose behavioral traits like permissions required, side effects (e.g., triggering workflows), or what happens on duplicate names.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with one sentence and a tag, no wasted words. However, it is slightly too brief for a tool with 6 parameters; additional context would be beneficial without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description is minimal and does not explain what a GRC risk is, the outcome of creation, or any necessary relationships. For a creation tool with 6 parameters and no output schema, the description should provide more context to ensure correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so each parameter is already documented. The tool description adds no extra meaning beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Create' and resource 'GRC risk entry', making the tool's purpose explicit. However, it does not differentiate itself from sibling creation tools like create_incident or create_record beyond the resource name, which is already implied by 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/5Does 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 other create tools or list_grc_risks. The description lacks context about prerequisites, typical use cases, or when it's appropriate to create a risk vs. update an existing 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?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description only adds the WRITE_ENABLED constraint. Other behaviors like return value or post-creation state are not disclosed. For a creation tool, this is insufficient 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with essential information (purpose and prerequisite). No wasted words. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too brief. It does not mention what the tool returns (e.g., sys_id of the new article), nor does it clarify whether the article is created as draft or published. With siblings like publish_knowledge_article, this context is missing. Incomplete for a creation 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no parameter-specific information beyond what the schema already provides. The schema's own descriptions are adequate but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new knowledge article', which is a specific verb and resource. It adds a prerequisite (WRITE_ENABLED=true). While it doesn't explicitly distinguish from siblings like update_knowledge_article, the verb 'create' provides inherent 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Only the prerequisite 'requires WRITE_ENABLED=true' is provided. There is no guidance on when to use this tool versus alternatives, no exclusions, and no mention of when not to use it. This is minimal guidance.
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. Annotations indicate it's not read-only and not destructive, but the description does not explain any side effects, required 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. The '[Write]' prefix is somewhat unusual but doesn't harm clarity. It is efficiently concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no output schema, and no explanation of what a KPI is or its relationship to Performance Analytics, the description leaves significant gaps for an AI agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the description does not need to add parameter details. However, the description provides no additional context beyond the schema, meeting only the baseline level.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a Key Performance Indicator from ServiceNow data. It distinguishes from other create_* tools by specifying 'Key Performance Indicator', but lacks detail on what a KPI entails in this 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/5Does 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 create_pa_indicator or other create_* tools. No prerequisites or context for usage 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?
Annotations already indicate readOnlyHint=false, so the description's [Write] tag adds no value. No other behavioral details (e.g., required permissions, side effects) are 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence plus tag), but it conveys the core purpose without extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with no output schema, the description should mention return values or confirmation. It is incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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. The tool description adds no further semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 (mobile applet), but does not differentiate from sibling tools like create_mobile_app_config or create_mobile_layout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 when creating a mobile applet vs. a mobile app config or layout.
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 indicate readOnlyHint=false and destructiveHint=false, but the description adds no behavioral context beyond confirming it's a write operation. It doesn't disclose side effects, required permissions, or any consequences 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a single sentence. However, it lacks structure (e.g., bullet points) and trades completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters (2 required) and no output schema, the description is insufficient. It doesn't explain the return value, what happens upon successful creation, the meaning of 'exit tasks,' or any related context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, but the tool description does not elaborate on any parameters. It adds no 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/5Does 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 (employee offboarding case) with additional detail about exit tasks. It distinguishes from sibling tools like create_onboarding_case and create_hr_case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, no prerequisites, and no exclusions. The '[Write]' marker is insufficient for usage decisions.
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 indicate it's a write operation (readOnlyHint=false) and not idempotent. The description adds 'recurring email delivery' but fails to disclose important behavioral details like whether it overwrites existing schedules, what happens on duplicate calls, or any rate limits. With annotations present, 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 8 words, very concise. However, the brevity omits potentially important information that could be included without sacrificing conciseness, such as prerequisites or output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters and no output schema, the description is insufficient. It does not explain the return value, any constraints on parameters (e.g., valid emali formats), or what constitutes success. A mutation tool with medium complexity needs more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are already documented with descriptions. The description adds no additional meaning beyond what the schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Schedule' and the resource 'report' with the purpose of 'recurring email delivery'. It effectively differentiates from sibling tools like 'create_report' which creates the report definition itself, making the purpose clear 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 Guidelines2/5Does 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 'generate_report' for one-time generation or 'schedule_notification' for other scheduling. It also lacks prerequisites (e.g., report must exist) or any conditions for use.
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 destructiveHint=true and readOnlyHint=false. The description adds minimal behavioral context (only 'background script'), failing to disclose side effects or execution outcomes 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences plus a tag, containing no unnecessary words. It could potentially include more useful information without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks important context such as asynchronous execution, potential side effects, and differentiation from 'execute_script'. Given the tool's destructive nature and lack of 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/5Does 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 tool description does not add additional semantic 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a background script (server-side JavaScript). However, it does not differentiate from sibling tools like 'execute_script', which might imply a different context (e.g., foreground vs background).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, nor any mention of prerequisites or exclusions. The description only states the action without context for decision-making.
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 no behavioral context beyond what is in annotations, such as permissions, rate limits, or what 'complete information' entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 9-word sentence, concise and front-loaded. However, it could include more useful information without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 params, no output schema, annotations present), the description is minimally complete but lacks details on output, error handling, and the implications of openWorldHint. It does not fully compensate for the 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with descriptions for both parameters. The description adds the phrase 'complete information' but does not elaborate on how to use the fields parameter or provide additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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', and implies completeness. It distinguishes from similar tools like 'search_cmdb_ci' which is for search, and other 'get_' tools, but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 that it is for retrieving a single CI by sys_id, nor does it contrast with search_cmdb_ci or list 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?
Annotations declare readOnlyHint=true and openWorldHint=true, which the description does not contradict. However, the description adds no behavioral context beyond these annotations, such as rate limits, data freshness, or that results may be incomplete due to open-world nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the key action and resources. Every word is necessary, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about the return format or structure. Since there is no output schema, the agent may struggle to interpret results. Behavioral details from annotations exist, but completeness for agent decision-making is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have descriptions in the input schema (100% coverage). The tool description adds no additional meaning beyond what the schema provides, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries threat intelligence data, specifically IOCs, threat actors, and campaigns. This provides a specific verb and resource, distinguishing it from many general query tools. However, it does not explicitly differentiate from other threat-related tools like 'scan_vulnerabilities' or 'get_vulnerability'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 scenarios, prerequisites, or when not to use it. Given the many sibling tools, explicit usage context is missing.
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, such as what 'active' means, pagination behavior, or return format. For a tool with annotations, the description should still add value 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.
Conciseness4/5Is 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 contains no fluff, but could be improved by adding usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 implies it returns a list of records. However, it does not specify return fields, what 'active' means, or how pagination works. Given the low complexity, it is marginally complete but not fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 description's 'optional filters' adds minimal extra meaning. It does not clarify the encoding of 'query' beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists active SLA records and mentions optional filters. It distinguishes from siblings like get_sla_details (which focuses on single SLA details) but does not explicitly differentiate from other list tools. However, 'active SLA records' is specific 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not specify when to use this tool versus alternatives like get_sla_details or other list tools. No explicit context or exclusions are 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 provide readOnlyHint and openWorldHint, which indicate read-only and potentially incomplete results. The description adds no behavioral context beyond the purpose. It does not mention pagination, ordering, or any side effects. Since the description does not contribute beyond annotations, score is low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb and resource, and contains no redundant information. Every word is meaningful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and a simple listing tool, the description is minimal. It does not explain what the returned results look like, how they relate to the suite result, or the default limit behavior. For a tool with many siblings, more context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have full schema descriptions, so the schema already documents them. The tool description does not add additional meaning or context for the parameters. 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'individual test results', and the scope 'within a suite run'. It distinguishes this tool from siblings like list_atf_suites and list_atf_tests by specifying 'test results' rather than suites or tests. However, it could be more explicit about the relationship to suite result.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. There are many sibling list tools (e.g., list_atf_suites, list_atf_tests) but no mention of when to choose this one. No prerequisites or exclusions are 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 provide readOnlyHint and openWorldHint, indicating safe, open-world reads. The description adds no additional behavioral traits such as pagination limits or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. However, it could include more contextual detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about return structure, default pagination behavior, and what 'connected and credential aliases' entails. Given no output schema, more detail is needed for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions in the schema. The description does not add extra meaning beyond what the schema provides, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists connection and credential aliases used by integrations. The verb 'list' is specific and the resource 'aliases' is defined, but it does not differentiate from other list tools among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over alternatives. The description only states what it does, without exclusions or preferred contexts.
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 annotations. Annotations indicate readOnlyHint=true and openWorldHint=true, but the description does not elaborate on these or mention any side effects, permissions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a single sentence. It is front-loaded and to the point, though it could benefit from a bit more context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description is minimally complete. It covers the basic function and parameters, but lacks details on pagination, default limits, and what constitutes a 'group'. The absence of an output schema is not a problem here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for both parameters (limit and query). The description adds only the vague notion of 'optional search filter' without enhancing meaning 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.
Purpose4/5Does 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 'groups', and mentions the optional search filter. It is specific enough to distinguish from other list_ tools, though it could be more explicit about the type of groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives. There is no mention of prerequisites, use cases, 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, so the description does not add behavioral context beyond that. It does not mention any side effects, rate limits, or behavior traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It could include more structured information about parameters or return value, but it is concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 provide context about what information is returned, but it does not. It also does not explain what 'mobile app configurations' are or any important constraints. Given the complexity of the tool (list with 2 params), the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool description does not explain any parameters; it relies on the schema. Schema coverage is only 50% (active has description, limit does not). The description adds no meaning beyond the schema, and does not compensate for the missing param descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'mobile app configurations', using a specific verb and resource. This distinguishes it from sibling tools like create_mobile_app_config, get_mobile_app_config, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 like get_mobile_app_config for a specific config, or create_mobile_app_config for creation. It does not mention context, prerequisites, 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=true and openWorldHint=true. The description adds no behavioral context beyond stating the action. It does not mention any side effects, required permissions, or return characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and to the point. No unnecessary words, but it could include slightly more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters, no output schema, and annotations that don't fully explain behaviour, the description is incomplete. It does not describe the return format, pagination, or error conditions, which are important for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions. The description does not add any extra meaning beyond what the schema provides. With 100% schema coverage, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists pages within a Next Experience (UI Builder) application. It is specific about the resource and action. However, it does not differentiate from the sibling tool 'list_uib_pages', which likely serves 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/5Does 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, limitations, or scenarios where other tools might 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 destructive write (readOnlyHint=false, destructiveHint=true). Description adds only a **[Write]** tag, providing no further behavioral details like permission requirements or delivery guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at one sentence plus a tag. No wasted words, but lacks structure (e.g., separate sections for behavior, usage). Appropriate for simple tool but could benefit from more detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with 5 parameters, the description omits important context like return value (confirmation?), error cases, and idempotency implications. Given no output schema, this gap is significant.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes parameters. The description does not add additional meaning beyond what's in the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it sends a push notification to mobile app users. The **[Write]** tag reinforces the action type. While it distinguishes from siblings via specific tool name, it lacks details on scope (e.g., which mobile apps).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 like `send_emergency_broadcast` or `schedule_notification`. No prerequisites or context 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?
Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds no behavioral context beyond a vague action. It doesn't disclose side effects (e.g., whether it creates a separate event record, updates the asset's stage field, or logs the transition). With annotations present, the description should provide more detail but fails to do so.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a short phrase. It is front-loaded and wastes no words. However, it is not a complete sentence and could benefit from slightly more specificity at minimal length cost.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters, no output schema, and minimal annotations, the description is insufficient. It does not explain what the tool returns or the exact effect of the operation (e.g., whether it updates the asset's stage field or creates a separate lifecycle event). More context is needed for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions for asset_id, new_stage (including allowed values), and notes. The tool description adds no additional semantic information beyond what the schema already provides. Baseline score of 3 applies as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: tracking asset lifecycle events and stage transitions. It distinguishes from siblings like create_asset and update_asset by focusing on stage changes, but the verb 'track' is slightly vague and could imply monitoring rather than recording.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. For example, it doesn't explain that this tool should be used to record a stage transition, while get_asset retrieves the current stage and update_asset modifies other attributes. No usage context or exclusions are 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?
Description adds that the tool requires WRITE_ENABLED=true, which implies write side effects, but beyond that it offers no disclosure of behavioral traits such as whether flows run synchronously, what happens on failure, or any potential side effects. Annotations already indicate readOnlyHint=false and destructiveHint=false, but 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that packs the core purpose and a key prerequisite. It is extremely concise without any wasted words, earning the highest score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks critical context: it does not mention what the tool returns (e.g., an execution ID), whether the flow execution is synchronous or asynchronous, or how to handle errors. With no output schema, the description should fill these gaps but fails to do so, making it incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides good descriptions for both parameters (flow_sys_id: 'sys_id of the flow to trigger', inputs: 'Key-value pairs for flow input variables'), covering 100% of parameters. The description only reiterates that inputs are optional, adding no new semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool triggers a 'Flow Designer flow' and mentions optional input parameters, which is specific and matches the tool name. However, it does not explicitly distinguish from sibling tools like trigger_agentic_playbook or test_flow, though the resource name helps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Only mentions a prerequisite (WRITE_ENABLED=true) but gives no guidance on when to use this tool versus alternatives such as trigger_agentic_playbook or execute_playbook. No when-not-to-use or scenario context is 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?
Annotations already indicate a readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds only '[Write]', which is already implied. No additional behavioral context (e.g., permissions, side effects, or what happens on update) is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: one sentence plus a tag. However, it lacks any structure (e.g., bullet points) that could enhance readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with a nested parameter (fields) and no output schema, the description is insufficient. It does not explain how to structure the fields object or what the tool returns, leaving agents with ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds no extra meaning 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Update an IT asset record' with a clear verb and resource. It distinguishes from siblings like create_asset and retire_asset, but does not explicitly differentiate from update_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 (e.g., update_record, retire_asset). No prerequisites or scenarios 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 no behavioral information beyond what annotations already provide. Annotations already indicate a write operation (readOnlyHint=false) and non-idempotent behavior, but the description only redundantly notes 'Write' without elaborating on side effects, prerequisites, or behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one sentence plus a tag), which is concise but lacks structure and fails to provide necessary detail. It is not efficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not explain return values (no output schema), possible constraints, or dependencies. Given the tool's complexity and lack of annotations, the description is insufficient for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, leaving one parameter (description) undocumented in the schema. The description does not supplement parameter semantics, so it merely meets the baseline for a tool with good schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 configurable agent workspace'), using a specific verb-noun pair that distinguishes it from other create tools. 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidelines are provided about when to use this tool versus alternatives (e.g., create_agentic_workflow). The description lacks context for decision-making among many sibling create 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?
The description states the tool runs a build command, which implies writing to disk, yet the annotation readOnlyHint is true, creating a contradiction. No other behavioral traits (e.g., file changes, network calls) are disclosed beyond the annotation contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences) and front-loads the purpose. It could be slightly more structured (e.g., separate prerequisites), but it is clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is adequate but lacks details about return values or side effects (e.g., build output location). The annotation contradiction further reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds no additional meaning beyond the schema's description of the directory parameter. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds a ServiceNow fluent/now-sdk project and provides the exact command run. This distinguishes it from sibling fluent tools like fluent_init (initialize) and fluent_query (query).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions required environment variables but does not provide guidance on when to use this tool versus alternatives (e.g., fluent_init before build) 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description need not state safety. However, the openWorldHint=true suggests results may not be exhaustive, but the description doesn't clarify this or disclose pagination, ordering, or that topics may be limited without category filters. The parenthetical (sys_cs_topic) adds a useful internal table reference not in the annotations, which is minor added value, but overall behavior details remain thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the parenthetical table reference adding useful precision. Every word earns its place - no filler. It's appropriately minimal though it could add a usage or behavior note without bloating.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple filtered-list tool with 3 self-documented parameters and no output schema, the description is minimally adequate. The readOnlyHint annotation covers safety. However, given the existence of a nearly identical sibling (list_va_topics_full) and the openWorldHint annotation, the description should clarify what distinguishes this listing from the alternatives and whether results are paginated or complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all three parameters (limit, active, category) are described in the schema. However, the description adds nothing beyond the schema - it doesn't give value hints for the category filter, explain the default limit behavior, or clarify whether 'active' interacts with category filtering. With full coverage, baseline is 3, but the description contributes zero value on top, pulling it slightly below.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Virtual Agent topics available in the instance (sys_cs_topic)' has a specific verb (list) plus a specific resource (Virtual Agent topics) and the underlying table reference. It distinguishes from siblings like get_va_topic (singular) and list_va_topics_full (which appears to be a fuller/alternative listing variant), though it doesn't explicitly differentiate from these siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 list_va_topics_full or get_ms_copilot_topics. There is no mention of when this is the preferred tool, prerequisites, or exclusions. The openWorldHint annotation implies non-exhaustive results but this isn't tied to usage guidance in the text.
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 claims the tool performs an update (write operation), but the annotations declare readOnlyHint=true, which is a direct contradiction. This severely misleads the agent about the tool's behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with 11 words, containing the essential action and a critical condition. It is concise and front-loaded without any redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description fails to explain what 'natural language update' entails, such as what fields can be updated or what the return value is. The contradiction with annotations also undermines completeness. The description needs more context to be fully useful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has full parameter descriptions (100% coverage), so the description adds no additional meaning beyond the condition that WRITE_ENABLED must be true. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'record using natural language', indicating a specific method (natural language) that distinguishes it from other update tools like update_record. It also mentions a requirement (WRITE_ENABLED=true), adding clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite (WRITE_ENABLED=true) but offers no guidance on when to use this tool over alternatives such as update_record or other update tools. It does not specify conditions where this tool is preferable 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 indicate readOnlyHint=false, but description only adds '[Write]'. No details about side effects, required permissions, or behavior beyond creation. With annotations present, 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence plus a tag, no wasted words. However, the '[Write]' tag is redundant and could be integrated. Still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks details on creation outcomes, error handling, or return values. No output schema. For a complex tool with 7 parameters and overlapping siblings, the description is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The tool description does not add any extra meaning or clarification 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/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'create' and resource 'change request' with specific context 'linked to a DevOps deployment for change governance'. Distinguishes from sibling tools like create_change_request by specifying the DevOps linkage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 (e.g., create_change_request). Does not mention prerequisites, context, or when not to use.
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 permission requirement, which is useful, but does not disclose other behavioral aspects like side effects or validation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, very concise, and front-loads the action. It includes a key requirement efficiently, though could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters and no output schema, the description is minimal. It does not explain what an HR case is, typical usage patterns, or how it relates to other HR entities, leaving the agent with insufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 6 parameters. The description does not add any additional meaning beyond what is already in the schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' and resource 'HR Service Delivery case', clearly stating the tool's purpose. However, it does not explicitly differentiate from sibling tools like create_hr_task or create_onboarding_case, though the unique resource name helps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a requirement 'requires WRITE_ENABLED=true', which is a usage condition, but it offers no guidance on when to use this tool versus alternatives such as create_hr_task or create_onboarding_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 indicate readOnlyHint=false (write operation) and destructiveHint=false. The description adds '[Write]' which is redundant. No additional behavioral traits like required permissions or side effects 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, effectively conveying the core purpose in a single sentence. It is efficient but could be slightly more descriptive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and lacks context about what a 'mobile layout' is, how it relates to the 'view', or what the resulting output looks like. For a tool with three parameters and no output schema, more explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so the schema fully documents the three parameters. The description adds no further meaning or usage details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 mobile layout for a specific view'). It is straightforward but does not differentiate from sibling tools like create_mobile_app_config, relying on the name for 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/5Does 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 lacks any context about prerequisites, when not to use, or comparison with 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 only adds '[Scripting]' which might imply a requirement, but does not disclose side effects, authorization needs, or other behaviors. Annotations already provide basic safety hints; 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence, 8 words), which is efficient for a simple create tool. However, it could be slightly expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and minimal annotations, the description is too brief. It omits details about the created component, return value, or script requirement implications, making it incomplete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (75%), and the description does not add any parameter-specific meaning beyond what the schema already provides. Baseline score of 3 is appropriate as the description is neutral.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 ('custom UI Builder component (macroponent)'), which distinguishes it from sibling tools like update_uib_component or list_uib_components. 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/5Does 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 '[Scripting]' hint is vague and does not explain prerequisites or context for use.
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 write behavior (readOnlyHint=false). The description adds '[Write]' which is redundant. No additional behavioral traits (e.g., side effects, authorization needs, constraints) are disclosed beyond what annotations or schema provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with one clarifying tag. It is concise and front-loaded, though some brevity sacrifices depth.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks context about the tool's output, prerequisites (e.g., what an 'app sys_id' is), or the nature of UX Experience configurations. With no output schema and only basic parameter info, the description is incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description need not add parameter details. The description does not elaborate on parameter semantics beyond what the schema already provides, which is adequate but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new UX Experience (app shell) configuration.' It uses a specific verb ('Create') and resource ('UX Experience'), with a clarifying parenthetical that differentiates it from sibling tools like create_ux_app_route or create_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/5Does 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. The '**[Write]**' tag is redundant with annotations and does not inform decision-making. Given the extensive list of sibling tools, this lack of context is a significant gap.
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 safety is clear. The description adds the table name but does not disclose ordering, pagination behavior (beyond limit), or whether results are sorted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundant words, front-loaded with the action and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output schema and does not describe the structure of returned playbook definitions. For a list tool with no output schema, more detail on response format would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single 'limit' parameter, and the description repeats the schema's explanation. No additional semantics are added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists playbook definitions from a specific table (sys_hub_action_type_definition), which is distinct from other list tools. However, it does not differentiate from similar tools like list_flows or list_subflows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 list_flows or list_subflows. The description lacks 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 declare readOnlyHint=true and openWorldHint=true. The description adds minimal behavioral context beyond the name (e.g., 'data sources for pages') but does not disclose details like pagination, sorting, or result limits. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Could include more detail without being verbose, but current structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 minimally adequate. However, it lacks information about default limit, return format, or relationship to other data broker operations (e.g., create_uib_data_broker).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 2 parameters with 50% coverage (only page_sys_id has a schema description). The tool description does not explain 'limit' or how 'page_sys_id' filters, adding no value beyond the schema. For a tool with partial coverage, baseline is lower and description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'UI Builder data brokers', and adds context that these are 'data sources for pages'. This distinguishes it from sibling list tools like list_uib_components and list_uib_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/5Does 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_data_sources or other list_* tools. No context about prerequisites or exclusions 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?
The annotations already indicate readOnlyHint and openWorldHint. The description adds no behavioral context beyond the purpose, such as how the forecast is generated or that results may vary. No additional transparency 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that front-loads the verb 'Forecast'. It is efficient but borders on being too terse; however, it wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is an ML forecasting function with no output schema, the description lacks details on return format (e.g., single number, time series) or model behavior. The agent may not have sufficient context to use the output correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 elaborate on parameters (category, priority, days_ahead), but the schema already documents them adequately, so no penalty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Forecast incident volume for the next N days based on historical trends' clearly states the verb (forecast), resource (incident volume), and scope (next N days). It distinguishes itself from sibling ML tools like ml_predict_change_risk or ml_similar_incidents by focusing on volume prediction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 ml_predict_change_risk or ml_similar_incidents. It lacks explicit usage context, exclusions, or prerequisite conditions.
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 indicate a write operation with no idempotency or destructiveness. The description adds only the redundant '[Write]' tag. No disclosure of behavior like whether training is async, how model versioning works, or impact on existing models.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded. The '[Write]' tag is somewhat redundant but not overly verbose. Slight deduction for wasted space on redundant tag.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a machine learning training operation, the description is too brief. It omits critical context like whether training is synchronous, expected duration, how to monitor progress, and what output to expect. No output schema exacerbates this gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear parameter descriptions. The tool description restates 'table/field' but adds no new meaning. Baseline score of 3 is appropriate as description adds minimal value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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' scoped to a specific table/field. It distinguishes from sibling training tools like ml_train_change_risk and ml_train_incident_classifier which target different models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 description lacks any context about prerequisites, when training is appropriate, or how it differs from other ML training 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?
Annotations already declare readOnlyHint=true and openWorldHint=true, indicating a safe, read-only operation. The description adds no further behavioral context (e.g., pagination, result format, or any side effects), and 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the core functionality without any extraneous words. It is front-loaded and efficient, earning its place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no output schema, the description is somewhat incomplete. It does not mention what type of results are returned (e.g., records, snippets, counts) or how they are presented. However, given the simple parameters and annotations, it is minimally adequate but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 in the schema. The tool description reiterates 'using plain English' for the query parameter but adds no additional meaning beyond what the schema already provides. Given the high 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search ServiceNow using plain English' clearly states the tool's function: it performs a search across ServiceNow records using natural language queries. While it doesn't explicitly differentiate from siblings like 'ai_search' or 'nlq_query', the focus on plain English input is distinctive enough to convey 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance on usage. It implies that the tool is appropriate when a user has a natural language query, but it does not specify when not to use it (e.g., for structured queries) or mention alternatives among the many sibling search tools (e.g., 'search_cmdb_ci', 'search_knowledge').
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 a URL and the list of aggregate functions but does not disclose behavioral traits beyond the annotations. The readOnlyHint=false annotation contradicts the expected read-only nature of an aggregate query, and the description does not clarify this inconsistency or mention idempotency, destructive potential, 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence but includes a URL that may not be essential for agent understanding. It is front-loaded with the 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.
Completeness2/5Given 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 tool returns (e.g., aggregated data, structure, pagination). It does not. The description also fails to address error handling, rate limits, or the contradiction in readOnlyHint=false. For a tool with 5 parameters, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters have descriptions in the input schema (100% coverage). The tool description adds minimal extra value by exemplifying COUNT, SUM, AVG but omits MIN and MAX listed in schema. Thus, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Run'), the resource ('grouped aggregate query on any table'), and specific aggregate functions (COUNT, SUM, AVG). It effectively distinguishes this tool from siblings like query_records (returns raw records) and trend_query (time-series).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, when-not to use, or contrast with sibling tools. The usage context is only implied by the tool's name and description.
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?
Description does not disclose side effects (e.g., CI creation or update), asynchronous nature, or permission requirements. Annotations indicate non-readOnly and non-idempotent, but description adds no behavioral context beyond 'Trigger a ... scan'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise. However, the '[Write]' prefix adds minor clutter. Overall, it is efficient but lacks depth.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is present, and the description does not explain return values or post-trigger behavior. For a tool that initiates a potentially impactful process, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and descriptions are provided for both parameters. The tool description does not add meaning beyond what the schema already conveys, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Trigger a ServiceNow Discovery scan' and the target resource 'network/infrastructure'. It distinguishes from sibling tools like 'scan_vulnerabilities' and '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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or when-not-to-use guidance is provided. Sibling tools like 'scan_vulnerabilities' or 'cmdb_find_duplicates' are not differentiated in terms of use case.
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 annotations already indicate readOnlyHint=false. No additional behavioral traits disclosed, such as queue behavior, rate limits, or what happens if a scan is already running.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus '[Write]', efficiently conveying the core action. No redundant information, though it could briefly expand on output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks description of return value (e.g., scan ID or status) despite no output schema. Does not differentiate from other scan triggers among many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description's mention of 'CIs or groups' adds little beyond the schema's descriptions of 'group' and 'ci_sys_ids'. No extra constraints or formatting details provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Trigger a vulnerability scan for specified CIs or groups.' The verb 'trigger' and resource 'vulnerability scan' are specific, and it distinguishes from sibling tools like 'run_discovery_scan' by focusing on vulnerabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 (e.g., 'run_discovery_scan' or 'list_vulnerabilities'). It does not specify prerequisites or context for optimal use.
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 destructiveHint=true and readOnlyHint=false. The description adds '[Write]' which is redundant with annotations and provides no additional behavioral details such as immediacy of delivery 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a clear verb prefix, no wasted words, and front-loaded structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic purpose but lacks details about side effects, delivery behavior, or return values. Given the lack of output schema and the tool's potential impact, more context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema's parameter descriptions, but that is acceptable given the high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Send' and resource 'emergency broadcast notification', making the purpose obvious. However, it does not explicitly differentiate from siblings like 'send_push_notification', which could cause 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/5Does 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 are no exclusions or context about appropriate usage 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 indicate write behavior (readOnlyHint: false) and non-destructiveness. Description adds no additional behavioral details beyond confirming write nature. The '[Write]' tag is 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is one concise sentence plus a bracketed tag. Front-loaded with verb and resource. However, the '[Write]' tag could be considered extraneous and disrupts flow slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no output schema, and no additional context, the description is insufficient. It does not explain return values, error conditions, or relationship to deployment validation or rollback. A more complete description would include expected behavior, prerequisites, or output hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 6 parameters. Description adds no extra parameter meaning beyond what schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('record') and resource ('deployment event'), and the context ('for audit and velocity tracking'). It distinguishes from read tools like get_deployment but does not explicitly differentiate from sibling write tools like validate_deployment or update_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, no prerequisites, no exclusions. For a write operation, it would be helpful to indicate that this should be used after a deployment is completed, not for initiating deployments.
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, idempotent, non-destructive write operation. The description adds the '[Write]' tag which aligns with annotations but does not provide further behavioral details 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with a useful '[Write]' tag. It is front-loaded and efficient, though it could be slightly expanded for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with 3 parameters and no output schema, the description is adequate but lacks details on return values, defaults, or behavior beyond basic configuration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds minimal value beyond the schema, only hinting at 'tables/records' without explaining parameter specifics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Configure' and the resource 'which tables/records are available offline in mobile'. It distinguishes the tool from siblings by specifying offline configuration, though it does not explicitly contrast with other mobile configuration 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/5Does 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, context, or scenarios where 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?
Annotations already indicate the tool is not read-only (readOnlyHint=false), and the description adds the requirement of WRITE_ENABLED. However, it does not disclose what happens on creation (e.g., state, return value), which is limited given no output 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the purpose and a key condition. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema covers parameters, the description lacks information about the return value (e.g., sys_id of created record). With no output schema, this is a gap. Additionally, given the large set of sibling tools, more context on how this fits into the problem management process would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 4 parameters (100% coverage), so the description does not need to add more. The description itself adds no extra parameter meaning beyond what's in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 problem record'), making the purpose explicit. However, it does not differentiate from other create tools like create_incident, which are siblings but have distinct names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('requires WRITE_ENABLED=true'), which is helpful, but it lacks guidance on when to use this tool versus alternatives (e.g., create_incident, create_change_request) 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.
- 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 a permission requirement (WRITE_ENABLED=true), but lacks details on side effects, return values, or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded. It could include more useful information without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 7 parameters and no output schema, the description is adequate but lacks return value information and context about the operation's outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all parameters. The description adds no 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create a Security Operations incident', which is a specific verb and resource. It is clear but does not explicitly distinguish from the sibling tool 'create_incident' for general 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only mentions a prerequisite (WRITE_ENABLED=true) but provides no guidance on when to use this tool versus alternatives like 'create_incident' or 'update_security_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?
Annotations already indicate this is a write operation (readOnlyHint=false) and not idempotent. The description adds the WRITE_ENABLED requirement but fails to disclose other behaviors like validation, duplicate handling, or response details, providing minimal added 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence efficiently conveys purpose and a key requirement. While concise, it could benefit from additional structure like bullet points for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 6 parameters and no output schema, the description covers basic purpose and a prerequisite but lacks details on return values, error conditions, or edge cases, 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so all parameters are described there. The description adds no parameter-level meaning beyond the schema, meeting the baseline but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'agile story/user story', distinguishing it from sibling tools like create_epic or create_scrum_task. It also specifies the requirement WRITE_ENABLED=true, further clarifying 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 Guidelines2/5Does 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 vs alternatives (e.g., update_story, create_epic). It only mentions a requirement, leaving the agent without context for choosing among many create_* 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?
Discloses creation and optional switching, but omits details like default value of switch_to (true), error behavior if a set with the same name exists, or the '[Scripting]' context implications. Annotations confirm non-idempotent/read-only behavior but no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise (single sentence with tag), but lacks necessary structure like usage examples or parameter elaboration; brevity sacrifices completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no output schema, and many sibling tools, the description fails to explain return value, side effects, or use cases, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with clear descriptions; the description only adds 'optionally switch to it' which aligns with switch_to parameter but adds no extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states action 'Create' and resource 'Update Set', with optional switching behavior, distinguishing it from siblings like ensure_active_update_set 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Does not explicitly indicate when to use this tool versus alternatives like switch_update_set or ensure_active_update_set; no guidance on prerequisites 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 contradicts the annotations: annotations declare readOnlyHint=true (read-only), but the description says it runs 'npx @servicenow/sdk init', which creates files and is a write operation. Furthermore, the description does not disclose side effects, such as project scaffolding or modification of the filesystem.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) and front-loaded: first sentence states purpose, second states prerequisites. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the conflicting annotations and lack of output schema, the description should explain what the init command does in more detail (e.g., creates a project directory, package.json, etc.). It is incomplete for a tool that has behavioral contradictions and no return value documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema describes all three parameters (name, template, directory) with 100% coverage. The description does not add additional 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool initializes a new ServiceNow fluent/now-sdk project and specifies the command it runs. This is distinct from sibling tools like fluent_build or fluent_explain, 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions required environment variables (FLUENT_ENABLED=true, WRITE_ENABLED=true), which provides usage constraints. However, it does not specify when not to use this tool or suggest alternative tools, leaving guidance minimal.
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 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence. It could be slightly more structured but is appropriately short.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with one parameter and no output schema, the description is adequate but does not specify what details are returned or any limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter sys_id, but the description adds no extra meaning beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 resource ('a specific test case'). It differentiates from sibling tools like get_atf_suite or get_atf_test_results by specifying 'test case'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. No 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.
- 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-only operation. The description adds no additional behavioral context beyond what annotations provide, so it meets the baseline but does not exceed it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that is front-loaded with the core purpose. There is no redundant or extraneous text, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 should ideally hint at the structure or nature of the returned details. It does not, leaving the agent without information on what data will be provided. The sibling 'list_devops_pipelines' likely returns summaries, but this tool's response format is unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'sys_id' is already described in the input schema as 'Pipeline sys_id'. The description adds no further semantic meaning or examples, and schema coverage is 100%, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get details of a specific DevOps pipeline' clearly states the action (get details) and the resource (DevOps pipeline). It distinguishes from the sibling 'list_devops_pipelines' by specifying 'specific'. However, it does not elaborate on what 'details' entail, which slightly reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. While it is implicitly for retrieving a single pipeline versus listing all pipelines, there is no mention of prerequisites or context such as ownership or permissions.
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 behavior (readOnlyHint=true). The description adds context about 'analyze' and 'recommend', implying analysis is performed. However, it does not disclose if any data is mutated, which 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the core functionality without unnecessary fluff. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details about what the tool returns (e.g., recommendations format, whether it's a list or narrative). Since there is no output schema, the description should clarify the output to set proper expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning both parameters are already documented in the schema. The description does not provide additional semantic information beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: analyzing software license usage and recommending optimizations. It is specific enough to distinguish from the sibling 'get_license_compliance', which likely focuses on compliance rather than optimization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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_license_compliance' or 'list_software_licenses'. The description does not specify prerequisites or contexts where it is most appropriate.
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 'get' aligns with read-only behavior. However, the description adds little beyond annotations—it does not disclose details like response format, aggregation, or data granularity. The bar is lowered by annotations, but the description still fails to provide meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, concise and front-loaded. It avoids waste but could be slightly more informative without becoming verbose. No structural issues.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with 4 parameters and full schema coverage, the description is adequate but incomplete. It does not explain the nature of the return data (e.g., data points interval, aggregation) or how the parameters affect the output. Lacks completeness for an agent to fully understand the tool's behavior without additional schema or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema itself documents all parameters (indicator_sys_id, start_date, end_date, limit). The tool description adds no parameter-specific information beyond the schema. Baseline of 3 is appropriate as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('get') and resource ('historical time-series data for a PA indicator'), and adds the purpose of identifying trends. It clearly distinguishes from siblings like 'get_pa_indicator' (metadata) and 'list_pa_indicators' (listing). However, it could be more precise about what 'PA indicator' means in 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/5Does 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 implies usage for trend analysis but offers no when-to-use, when-not-to-use, or comparison with sibling tools such as 'get_pa_indicator' or 'list_pa_indicators'.
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 does not need to repeat safety. However, it adds no further behavioral details such as session scoping or pagination behavior, resulting in only adequate coverage 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no verbose elements. It directly states the tool's purpose, though it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 params, read-only), the description is somewhat complete but lacks details about return value structure (no output schema) and usage context, 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/5Does 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 additional meaning about parameters; the schema already describes both conversation_id and limit adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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, using a specific verb and resource. However, it does not differentiate from sibling tools like list_va_conversations, which might list all conversations, missing explicit 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks any guidance on when to use this tool versus alternatives. No context is provided about prerequisites, scenarios, or when not to use it, 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 declare readOnlyHint=true and openWorldHint=true, so the description carries minimal additional burden. It does not add details about pagination, sorting, or result format beyond what the annotation implies. The description 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is appropriately sized for a simple list tool, though a bit more context could be added without losing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool and good schema/annotation coverage, the description is adequate but not complete. It does not mention that the results may represent all approvals in the system or that filters are optional but typically used for large datasets. No output schema exists, but that is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage, so the description adds only that all parameters are 'optional filters', which is already clear from the schema. No additional syntax or meaning is provided beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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. It uses a specific verb-resource combination ('List approval requests') and distinguishes it from siblings like approve_request, reject_request, and get_my_approvals by not focusing on a single user or 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/5Does 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 get_my_approvals or query_records. There is no indication of when not to use it or which sibling to prefer in specific 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?
Annotations already declare readOnlyHint and openWorldHint. Description does not add behavioral context beyond stating the operation; it omits details like pagination, default limit (20 from schema not mentioned), or result 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundant words. Efficiently communicates core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no description of return values. For a listing tool, the agent lacks information on what fields are returned, pagination behavior, or how to interpret results. Incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters (100% coverage). Description adds minor context by mentioning optional suite filtering, but does not explain parameter 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/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists ATF test cases with optional suite filtering. It differentiates from siblings like list_atf_suites (lists suites) and list_atf_test_results (lists 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/5Does 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_atf_suites or get_atf_test. The phrase 'optionally filtered by suite' implies a use case but lacks when-not or alternative recommendations.
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 cover safety and multivalue return. The description adds no further behavioral details (e.g., pagination, sorting, or default filters). It is consistent with annotations but does not enhance understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 5 words, efficiently conveying the purpose with no wasted words. It is front-loaded and appropriate for such a tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite annotations and schema covering parameters, the description lacks output structure information. There is no output schema, and the description does not explain what the returned audit results look like, their order, or pagination behavior. This is incomplete for an AI agent to fully utilize.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have descriptions in the input schema (100% coverage), so the tool description adds no extra meaning. The schema clearly documents limit, state, and severity parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists audit results and findings, with a specific verb and resource. However, it does not distinguish from other list tools like list_incidents or list_approvals, which may cause confusion among the many 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 Guidelines2/5Does 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. With a long list of sibling tools including many list_* and search_* tools, the AI is left without context on when to choose list_audit_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=true and openWorldHint=true. The description adds 'available' but does not explain what that means or any additional behavioral constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It could be improved with more structure, but it is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with optional parameters, the description is adequate. However, it lacks details about return format or pagination, which is not provided by an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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. The description does not add any extra meaning beyond what the schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List available service catalog items' using a specific verb and resource. However, it does not differentiate from sibling tools like 'search_catalog' or '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 Guidelines2/5Does 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. For instance, 'search_catalog' might be used for more flexible searching, but this is not 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 already provide readOnlyHint and openWorldHint. Description adds no new behavioral context beyond repeating filter parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words, but could be slightly more structured (e.g., bullet points for filters).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with full schema coverage and annotations, description is adequate but does not mention return format or pagination behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description summarizes filters but does not add 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/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists CSM cases and mentions optional filters, which is specific and distinguishes it from 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 Guidelines2/5Does 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 (e.g., get_csm_case or search tools). Only implies usage via 'optional filters'.
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 provide readOnlyHint and openWorldHint, so behavioral basics are covered. Description adds no extra details about pagination, ordering, or response structure beyond what 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Could be improved but is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a list tool with good schema and annotations, but lacks detail on default behavior (e.g., returns all if no parameters) and no output schema to describe return fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 3 parameters. Description adds minimal context (account vs search) but doesn't provide new meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists contacts with optional filtering by account or search, which is specific and distinguishes it from sibling get/list tools. However, 'CSM contacts' could be more explicitly defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 get_csm_contact or other list tools. No when-not or context 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, indicating no side effects and potentially many results. The description adds the optional filter capability but does not detail pagination behavior or response structure. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Exceptionally concise at 11 words, front-loaded with the key action and resource. No wasted words. Could include a brief usage note, but it's efficient enough.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with annotations and schema, the description is passably complete. However, with no output schema, it would benefit from mentioning what fields are returned (e.g., flow name, status) to manage agent expectations. Currently minimal but not deficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear parameter descriptions. The description only restates that filters are optional, adding no new meaning beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly specifies the verb 'List' and the resource 'Flow Designer flows'. Mentions optional filters, which aids in distinguishing from other list tools like list_subflows or list_process_automations. However, it could be more explicit about what constitutes a Flow Designer 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives. Does not mention that for a specific flow's details, 'get_flow' should be used, or how it compares to other list tools. A sentence with usage context would improve this.
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 minimal behavioral context, confirming it lists a specific type of page. No additional traits like pagination or auth requirements are mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no extraneous information. It is concise and front-loaded, though it could be slightly more structured with explicit scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with annotations covering safety and open world, the description provides sufficient context to understand its purpose. No output schema exists, but the description adequately defines what is listed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have descriptions in the schema (100% coverage). The description adds no additional meaning beyond what the schema provides, so baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists homepage dashboards and clarifies they are CMS content pages used as homepages. It uses a specific verb and resource, but could more explicitly distinguish from sibling tools like list_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 Guidelines2/5Does 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. It does not mention when not to use it or suggest 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 and openWorldHint. The description adds 'verify they are healthy', implying some behavioral check beyond mere listing, but does not detail what verification involves or what happens if a server is unhealthy. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) with no wasted words. It front-loads the core action. However, it could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 and no output schema, the description is adequate but incomplete. It lacks explanation of what 'verify healthy' means or what the output looks like, which would be helpful for full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter well-described in the schema. The description does not add any extra meaning or context for the parameter, so it meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists MID servers and verifies they are healthy, specifying the resource and action. It distinguishes from other list tools by focusing on health verification, but could be more precise about what 'verify healthy' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. With many sibling list tools, the description should clarify that this is for MID server health checks, but it does not provide when-not-to-use or mention any 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 declare readOnlyHint and openWorldHint. The description does not add behavioral details beyond these annotations, such as pagination behavior, default limit, or potential for partial 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 the return value or structure of the list. For a list operation, it would be helpful to mention that the response contains dashboard objects with their properties.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have descriptions. The description adds no additional meaning; it merely restates the tool's function. 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Performance Analytics dashboards' clearly states the action (list) and the resource (Performance Analytics dashboards), distinguishing it from sibling tools like get_pa_dashboard (specific dashboard retrieval) and create_dashboard (creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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_pa_indicators or list_pa_breakdowns. The description lacks context on usage 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?
The description claims to list 'all' configurations, but the openWorldHint annotation indicates the tool may not return the complete set. This is a contradiction. Additionally, no details on pagination or default behavior beyond the schema are 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence with no extraneous words. Efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with optional params and an output-free schema, the description is minimally adequate. However, it omits mention of defaults or response format, which could be helpful given the lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not elaborate on the parameters (limit and query). Since schema coverage is 100%, the description adds no extra value; the agent must rely solely on schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all Service Portal configurations. It uses specific verb and resource, and distinguishes from sibling tools like list_portal_pages or list_portal_themes by focusing on configurations themselves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 such as get_portal or list_portal_pages. The description does not 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 declare readOnlyHint=true and openWorldHint=true, so the description is not required to repeat those. It adds minimal behavioral context ('reusable across flows'), but does not disclose pagination, authorization needs, or any other behavioral traits 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It could be slightly more informative (e.g., mentioning filtering capabilities), but it is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (list with optional filters) and the presence of annotations and full schema coverage, the description is adequate. However, it does not mention return value format or pagination behavior, and the term 'subflows' may require additional context for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% – all three parameters (limit, query, active) have descriptions in the schema. The description does not add additional meaning or usage hints for any parameter, so it remains at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List' and resource 'available subflows' and adds context 'that can be reused across flows'. However, it does not differentiate from sibling tools like list_flows, which are similar in nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 (e.g., list_flows, list_playbooks). No explicit when-to-use or when-not-to-use instructions are 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 indicate readOnlyHint: true and openWorldHint: true, so the description adds no additional behavioral context such as pagination behavior, sorting, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the essential information. No unnecessary words are present, though it could benefit from slightly more context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description is minimally adequate. However, it does not explain the structure of categories or any filtering or ordering options, which would be helpful for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the single parameter 'limit' with a description. The tool description does not add further meaning beyond what the schema provides, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Virtual Agent topic categories' clearly states the verb (List) and the resource (Virtual Agent topic categories), distinguishing it from sibling tools like 'list_va_topics_full' and 'list_va_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/5Does 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_va_topics_full' or other listing tools. The description lacks context for selecting the appropriate 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 non-read-only, non-idempotent, non-destructive. Description adds '[Write]' tag and implies state modification, but does not specify if training is asynchronous, side effects, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: single sentence plus tag, front-loaded with action verb. No unnecessary wording, effective for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and one optional parameter, the description is too minimal. Missing details on training duration, output, monitoring, or how to interpret results. Agent would need additional tools for full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the single optional parameter with description. No additional semantic value added in the tool description beyond what schema provides. Baseline 3 due to 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action 'Trigger training' and the resource 'change risk prediction ML model', clearly distinguishing it from other ML training tools like ml_train_anomaly_detector. However, it does not elaborate on the scope or outcome.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 ml_predict_change_risk or ml_model_training_history. Missing prerequisites or context for triggering retraining.
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 description adds little beyond listing capabilities. It does not mention potential rate limits, pagination behavior, or that it returns a list of records. The description is 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently lists the tool's capabilities. It is well-structured and front-loaded, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the good schema coverage and annotations, the description does not explain the output format or that it returns a list of records. For a query tool, this leaves some ambiguity, though it is functional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 parameters. The description's mention of 'filtering, field selection, pagination, and sorting' maps to existing schema fields but adds no additional meaning or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it queries ServiceNow records with filtering, field selection, pagination, and sorting. It uses a specific verb and resource, but does not explicitly distinguish itself from sibling tools like get_record or list_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/5Does 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_record for a single record or list_* tools for specific tables. No prerequisites or when-not-to-use information is included.
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, so the description's mention of 'mark as outdated' adds minimal context. It doesn't specify what exactly happens (e.g., status change, visibility impact) or whether the action is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one phrase) and front-loaded, but it lacks necessary detail. It is concise but under-specified for a mutation tool with destructive behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, no output schema, and annotations, the description should provide more context about the retirement process (e.g., impact on knowledge base, permission requirements). It feels incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'article_id' has full schema coverage (100%) with a clear description. The tool description adds no additional meaning beyond 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retire') and resource ('knowledge article'), with a parenthetical clarification ('mark as outdated'). This distinguishes it from sibling tools like 'publish_knowledge_article' and 'delete_record'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 'delete_record' or 'update_knowledge_article'. There are no prerequisites or context about when retirement 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 a write operation (readOnlyHint: false). The description adds '[Write]' but nothing beyond that—e.g., what side effects occur (sending invites, creating records). No new 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Front-loaded with the action and resource. Could include a brief note on parameters or usage, but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 4 parameters, no output schema, and no complex nested objects. The description states the purpose but lacks context like prerequisites (e.g., 'change_id must be valid') and outcome (e.g., 'creates a meeting record'). Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already explains all parameters. The description adds no additional parameter meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action 'Schedule' and the resource 'Change Advisory Board (CAB) meeting', which is specific and distinguishes it from sibling tools like 'schedule_notification'. 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 Guidelines2/5Does 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 (e.g., creating a change request separately). No prerequisites or context about when scheduling 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 declare readOnlyHint=true and openWorldHint=true, so the description adds no additional behavioral information. It does not disclose result format, pagination, or search behavior beyond the bare purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and only a minimal purpose statement. Important context like return format, ranking, or query syntax is missing, making it less complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 3 parameters with descriptions (100% coverage). The description does not add extra meaning 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search'), the resource ('knowledge base articles'), and the method ('by keyword'). It is specific and distinguishes from sibling tools like 'natural_language_search' and '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/5Does 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 'natural_language_search' for natural language queries. The description lacks explicit context for choosing this 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 non-read-only, non-destructive, idempotent. Description adds the WRITE_ENABLED requirement, but no additional behavior like merging vs replacing fields or handling of nested objects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no unnecessary words. Clearly states purpose and a critical requirement. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no return value description. Does not explain what a 'task' is or how partial updates work. For a mutation tool with nested parameters, more detail is needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% with descriptions for both parameters. Description does not add semantic detail beyond what is 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Update fields on a task record', specifying a verb and resource. It distinguishes from generic 'update_record' but does not define what qualifies as a task vs other record 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a prerequisite ('requires WRITE_ENABLED=true') but no guidance on when to use this tool vs other update tools (e.g., update_incident). No criteria for selection or exclusion.
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?
Description claims a read-only operation ('Retrieve'), but annotations have readOnlyHint=false, which suggests the tool may not be read-only. This is a contradiction. The description does not clarify the discrepancy or provide additional behavioral context 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence that front-loads the purpose and scope. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 is minimally sufficient. However, the contradiction with annotations detracts from completeness, and no information is given about response format or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'names' described as 'Array of property names to retrieve'. The description adds no additional semantics beyond the schema, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action 'Retrieve multiple system property values' and specifies the resource 'system property values' and the scope 'in a single call'. It distinguishes from siblings like 'get_system_property' (single) and 'bulk_set_properties' (write).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage when needing multiple properties in one call but does not explicitly state when to prefer over alternatives like 'get_system_property' or 'list_system_properties'. No exclusion criteria or prerequisite information 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 destructiveHint=false and readOnlyHint=false, consistent with a non-destructive write operation. The description adds that the operation makes the set ready for migration, but does not clarify reversibility, side effects, or what happens to the set's contents. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of one sentence and a tag. Every word serves a purpose, and it is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 minimal description provides adequate information about the action. However, it lacks context on prerequisites, return values, or error conditions, which would be beneficial for a state-changing operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter 'sys_id' with full coverage (100%). The description adds no additional meaning beyond 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: marking an update set as complete and ready for migration. It distinguishes from sibling tools like create_update_set or preview_update_set. The [Scripting] tag adds context for programmatic use. However, it could be more precise about what 'complete' entails, e.g., finalizing the set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 like preview_update_set or export_update_set. The [Scripting] tag hints at programmatic use, but no comparisons or exclusions are 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 indicate write, non-destructive, non-idempotent. Description adds '[Write]' but no additional behavioral context (e.g., authorization needs, duplicate handling, output format).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a useful '[Write]' prefix. It is front-loaded and concise, though it could be more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and moderate complexity, the description lacks crucial context: what happens if relationship already exists, validation details, return value (e.g., sys_id). The annotations cover basic safety but not operational completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (each parameter has a description). The tool description does not add any extra meaning 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create a relationship between two CMDB Configuration Items', which is a specific verb+resource combination. It clearly distinguishes from generic create_record or other CMDB 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives (e.g., list_relationships, create_record). Usage is only implied by the 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?
Annotations already indicate the tool is not read-only (readOnlyHint=false). The description adds the specific requirement of WRITE_ENABLED=true, providing context beyond annotations. However, it does not disclose other behavioral traits like 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with a parenthetical requirement, front-loading the core purpose. No wasted words, but could be slightly more structured if needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about return values (e.g., sys_id of created epic) and does not explain behavior when the WRITE_ENABLED condition is false. Given no output schema, this is a significant gap for a create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The tool description adds no extra information about parameters beyond what the schema provides, meeting the baseline but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new epic, using a specific verb and resource. It distinguishes from siblings like update_epic by the action 'create', though it doesn't explicitly address 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a usage prerequisite ('requires WRITE_ENABLED=true'), but lacks guidance on when to use this tool vs other epic-related tools or alternatives. No exclusions or context 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 write operation (readOnlyHint=false) and open world behavior. The description adds '[Write]' but little else beyond the annotations. It does not clarify permissions, side effects, or 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence and no extraneous text. It front-loads the core purpose immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no output schema), the description is minimal. It does not explain the role of a Flow Designer flow or how it relates to other flow entities, leaving some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema description coverage is 100%, so parameters are fully defined there. The description adds no additional meaning or context to the parameters, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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'), making the tool's purpose unambiguous. However, it does not differentiate from sibling tools like create_subflow or create_flow_action, missing a specificity 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/5Does 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 (e.g., create_subflow, create_flow_action). The description lacks context about prerequisites or appropriate 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?
Annotations already indicate a write operation (readOnlyHint=false) and non-idempotent. Description only adds '[Write]' tag, which is redundant. No details on side effects, permissions, or what happens to the update sets (e.g., are they copied or moved?).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise with one sentence plus a tag. Could be more structured (e.g., bullet points) or include additional context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks explanation of what a 'solution package' is or the distribution context. No output schema, but description could provide minimal behavioral overview. Incomplete for a tool with moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 67% of parameters with descriptions (name and update_sets). Description does not add any parameter guidance beyond the schema. The 'description' parameter lacks schema description and is not explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'create a solution package' and the source 'from selected update sets for distribution'. Distinguishes from sibling tools like create_update_set or export_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for creating distribution packages from update sets. Does not explicitly mention when not to use or alternatives, but 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate mutating (readOnlyHint=false) and non-destructive (destructiveHint=false), but the description adds only the vague '[Scripting]' tag, which hints at required permissions but does not explain it. No details on side effects, error scenarios, or limitations 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a functional tag. It is front-loaded with the primary purpose and contains no unnecessary words or repetition. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with four parameters and no output schema, the description adequately states the outcome but omits important context like response format (e.g., the sys_id of the created broker), required permissions beyond the '[Scripting]' hint, or error conditions. It is minimally complete but lacks depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all four parameters with names and descriptions. The description adds no extra meaning or usage examples for the parameters (e.g., how 'query' should be formatted or what 'page' expects). With 100% 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/5Does 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'). This distinguishes it from sibling creation tools like create_uib_component or create_uib_page, which target different UI Builder entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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_uib_data_brokers for retrieval, or other create tools). There are no prerequisites, context boundaries, or exclusions mentioned, 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?
The description includes the '[Write]' tag, which explicitly marks this as a write operation, adding clarity beyond the annotations (readOnlyHint=false). No other behavioral traits (e.g., side effects, required permissions, error conditions) are disclosed. With annotations present, the description adds minimal value but is 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a single sentence and a bracketed tag. Every word is functional, and the most critical information is front-loaded. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with a simple input schema and no output schema, the description covers the essential purpose and write nature. However, it lacks information about return values, validation behavior, or constraints. Given the limited complexity, 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/5Does 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. The description does not add any additional meaning or context beyond what's in the schema. Baseline score 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('register') and the resource ('new route (URL path) in a UX app'). It is specific and distinguishes this tool from siblings that create other entities (e.g., 'create_uib_page', 'create_ux_experience'). However, it could be more explicit about linking the route to a target page, which is a key aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 not to use it, or how it differs from similar create tools. The agent has to infer usage from the name and 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 and openWorldHint=true. The description adds a [Write] tag but no additional behavioral details (e.g., duplicates, permissions, side effects). With annotations present, the bar is lower, but the description 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—one sentence with a tag. No wasted words, but it is also under-specified. However, conciseness is not penalized if the content is adequate; here it is minimal but efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 5 parameters and no output schema, the description does not explain return values, error conditions, or usage notes. Annotations provide some context, but overall completeness is low for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 5 parameters with full descriptions (100% coverage). The description does not add meaning 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/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool creates a Virtual Agent conversation topic, with a prominent [Write] marker. It is distinct from siblings like update_va_topic 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/5Does 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. No prerequisites, context, or exclusions are provided. Among many create_* siblings, no differentiation is offered.
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=true and openWorldHint=true, so the safety profile is clear. The description adds only 'including test count,' which provides minimal behavioral context. It does not disclose other potential behaviors, side effects, or the scope of returned data beyond that hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, brief sentence that conveys the essential purpose without extraneous 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of annotations, the description is adequate but not comprehensive. It mentions the return includes 'test count,' but with no output schema and openWorldHint, more detail about possible fields or structure would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions. The description does not add additional meaning beyond what the schema provides for the single parameter 'sys_id_or_name'. With full 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/5Does 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 resource ('test suite'), and specifically mentions what is included ('test count'). This distinguishes it from sibling tools like list_atf_suites (which returns a list) and get_atf_test (which targets a single test, not a suite).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not specify when to use this tool versus alternatives. It lacks guidance on when not to use it or which sibling tools might be more appropriate (e.g., list_atf_suites for multiple suites, get_atf_suite_result for results). Without such context, an AI agent may not correctly select this 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 and openWorldHint. The description does not add any behavioral context beyond that, such as data freshness, scope, or result format. It neither contradicts nor 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loading the purpose. However, it lacks detail that could be added without significant bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and two optional parameters, the description should explain what the results contain and behavior when no parameters are provided. It fails to do so, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% description coverage for both parameters. The description's mention of 'policy or control' adds no new meaning beyond the parameter names and descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'compliance assessment results' with two specific identifying parameters (policy or control). This distinguishes it from sibling tools like list_compliance_policies or get_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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidelines are provided on when to use this tool versus alternatives (e.g., list_compliance_policies, get_grc_risk). The description does not mention prerequisites or typical 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, confirming safe read operation. The description adds the list of metrics, but does not disclose potential performance implications, data freshness, or the meaning of 'analyze' (e.g., real-time vs. cached). With annotations covering safety, the description provides moderate 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that immediately conveys the tool's purpose. Efficient and front-loaded, though could briefly mention parameter defaults without significant bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, yet the description does not hint at the return format (e.g., whether metrics are returned as a list or object). Missing details on aggregation period defaults and behavior when both parameters are omitted. For a metrics tool, more context is needed, especially given the tool's name suggests analytical output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to elaborate on parameters. It mentions 'for a pipeline' but does not clarify that pipeline_sys_id is optional or explain default behavior for days. Adds no value beyond the schema, meeting baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves three specific metrics (deployment frequency, failure rate, lead time) for a pipeline, using a strong verb ('Get'). This distinguishes it from siblings like get_deployment (individual deployment) and get_devops_pipeline (pipeline configuration).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 track_deployment or get_atf_failure_insight. Does not specify conditions for using optional parameters or situations where other tools are preferred. Lacks explicit 'when not to use' or context 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 declare readOnlyHint=true, so the description's mention of 'retrieve' is consistent but adds no additional behavioral context beyond what is in the annotations. No contradictions are 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single succinct sentence of 10 words, front-loaded with the verb and object. It contains no unnecessary words or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no output schema, and the description is minimally adequate. However, it does not explain the return format or any default behavior, such as whether all fields are returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all three parameters, achieving 100% coverage. The tool description does not add any extra meaning or clarification beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (retrieve), the resource (record), and the method (by sys_id). It is a generic tool that works on any table, but it does not explicitly differentiate itself from specialized sibling tools like get_incident or get_user, which may offer more tailored functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 when not to use it (e.g., for searches by other criteria, use query_records) or note any prerequisites like required permissions.
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 that the tool lists 'maintenance and support contracts,' which is useful context but does not disclose additional behavioral traits such as pagination behavior, default sorting, or the meaning of 'active' defaulting to true. With annotations covering safety and expansiveness, the description provides adequate but minimal 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/5Is 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 resource, making it easy to scan. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 optional parameters, no output schema), the description covers the basic purpose. However, it omits useful context such as the default behavior of the 'active' filter (true) and does not mention that results are paginated via the 'limit' parameter. The openWorldHint implies many results, but the description could be more complete by noting typical use cases or expected result format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (limit, active, asset_sys_id) have descriptions in the input schema, achieving 100% coverage. The tool description does not add any additional meaning beyond the schema. Per the rubric, when coverage is high, baseline score is 3, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 'asset maintenance and support contracts', making the purpose immediately understandable. It distinguishes from siblings like 'list_assets' by specifying 'maintenance and support contracts' rather than generic assets. However, it does not explicitly differentiate from other contract-related list tools like 'list_software_licenses'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 when not to use it, nor does it reference sibling tools like 'list_assets' or 'list_software_licenses'. The agent is left to infer context 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. The description adds no behavioral details beyond the annotations, such as pagination, sorting, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the main action. It is efficient but could benefit from a bit more structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and the description fails to specify what fields are returned or how the list is ordered. For a tool with 6 optional parameters, more completeness is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description's mention of filtering adds little beyond what the schema already provides. It does not explain all parameters (e.g., limit, query, location). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List IT assets' with specific filtering options (state, class, assigned user). It distinguishes itself from many sibling tools that list other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions optional filtering but provides no guidance on when to use this tool versus alternatives like 'search_cmdb_ci' or 'get_asset'. No explicit when-not 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=true and openWorldHint=true, signaling safe read and potential partial results. The description adds no further behavioral details (e.g., pagination, default limit, response structure), so it 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with key information. However, it sacrifices completeness for brevity, missing usage guidelines and behavioral context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 should explain return format, pagination, or common use cases. It fails to do so, leaving gaps in understanding what output to expect and how to handle results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for all three parameters. The description does not add any additional meaning or context beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'attachments', and the context 'associated with a specific record', making the tool's purpose unambiguous. It distinguishes from sibling tools like upload_attachment and delete_attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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_attachment_metadata or upload_attachment. The description does not specify context, 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 and openWorldHint=true, so the description adds no new behavioral insight. It does not contradict annotations, but it fails to disclose additional traits such as pagination or 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, 12-word sentence with no wasted words. It is concise and front-loaded with the core action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not explain return format, default behavior (e.g., limit of 10), or how the query parameter should be encoded. While schema covers some details, the description alone leaves gaps for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description merely echoes 'state or query' and does not add new meaning beyond the schema's descriptions for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 'change requests', specifying optional filtering. It distinguishes itself from sibling list tools (e.g., list_incidents, list_assets) by naming the specific entity, but does not explicitly compare or differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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_change_request for single records or search tools for complex queries. The description lacks 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?
Adds one behavioral trait (prerequisite) beyond annotations. Does not describe pagination, ordering, or output format. Annotations already provide readOnlyHint and openWorldHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output format description. For a list tool without output schema, more detail on returned data would improve completeness. Schema partially compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides 100% coverage with parameter descriptions. Description adds no additional parameter information, 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Verb 'List' and resource 'update sets (changesets)' are clear. Clarifies that update sets and changesets are the same. However, sibling 'list_update_sets' exists without 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Only provides a prerequisite ('requires SCRIPTING_ENABLED=true'). No guidance on when to use vs alternatives like 'get_changeset' or 'list_update_sets'.
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 adds modest context ('recent') but does not expand on behavioral traits like pagination, ordering, or rate limits. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the purpose. Every word adds value, with no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with thorough schema documentation and annotations, the description is adequate. However, it lacks details on default behavior (e.g., default limit of 50 is in schema but not description) and does not clarify the output format, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents the three parameters (limit, state, event_name). The description adds no additional meaning beyond the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List recent event log entries (fired events and their processing status)', specifying the verb and resource. While it distinguishes the tool as focusing on event logs among many list_* siblings, it does not uniquely differentiate its scope or usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 listing tools or alternatives. There is no mention of context, 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 and openWorldHint=true. The description adds no extra behavioral context beyond 'List...entries'. It doesn't explain implications of openWorldHint (e.g., external data sources) or any operational behaviors like pagination 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundant words. Structurally concise, but could benefit from a brief second sentence on usage context. Still, no unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite high schema coverage and annotations, the description omits key context for an open-world tool. No mention of what fields are returned, ordering, or that results may include external data (as hinted by openWorldHint). Lacks completeness for effective agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage (limit, state, category described). The tool description does not mention or elaborate on these parameters, adding no value 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List GRC (Governance, Risk, Compliance) risk entries', providing a clear verb and resource. It distinguishes from sibling tools like 'get_grc_risk' (singular retrieval) and 'list_grc_controls' (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 Guidelines2/5Does 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. No identification of prerequisites, use cases, or exclusions. With many sibling list tools, such context is needed but absent.
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 such as pagination behavior, whether inactive services are included, or rate limits. It merely restates the list action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a single sentence with clear examples. However, it could be slightly more structured, e.g., mentioning the parameter purpose, but it remains effective and not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having good schema coverage and annotations, the description lacks completeness. It does not mention return format, typical use cases, or behavior when no filters are applied. For a simple listing tool with optional params, more context would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (limit, query, active) have full descriptions in the input schema (100% coverage). The description does not add parameter-level details 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists available HR services with examples (Onboarding, Offboarding, Benefits, Payroll, etc.), which differentiates it from sibling tools like get_hr_service that would retrieve details of a single service.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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 vs alternatives. While the context of listing is implied, there is no guidance on not using it for single-service details or when to apply filters.
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 behavioral burden is reduced. The description does not add new information about behavior (e.g., performance, pagination, result 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that efficiently states purpose and optional filters with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool without output schema, the description is adequate but lacks details on return fields, pagination beyond limit, and behavior when no filters are applied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds 'staging table' filter, which is not directly represented as a parameter, offering some added meaning but not fully compensating for the schema's detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists import sets, with optional filters by state or staging table. However, the schema only has a 'state' parameter and a generic 'query', not a dedicated 'staging_table' parameter, causing slight mismatch with the 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/5Does 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 'get_import_set' or other list tools. The description provides no context on when to filter by state vs. staging table, 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 indicate readOnlyHint=true and openWorldHint=true, so the description adds only 'recent' and 'success/failure log' context. It does not disclose ordering, pagination, or result format, but it aligns with annotations and adds 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the core purpose without waste. While concise, it could benefit from slightly more structure, such as listing the primary use case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and the complexity of a list tool, the description does not explain return format, ordering, or pagination behavior. It provides only high-level purpose, leaving significant gaps 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/5Does 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 does not add any meaning beyond the parameter descriptions in the schema, such as the effect of 'limit' or 'status'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'recent run history for scheduled jobs (success/failure log)', specifying the verb (list), resource (job run history), and scope (recent, scheduled jobs, success/failure). This distinguishes it from sibling list tools like list_scheduled_jobs or list_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives, nor does it mention when not to use it. It only implies usage for viewing run history, lacking explicit 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 no further behavioral context (e.g., pagination behavior, result format), which is acceptable given the annotations cover the main concerns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that is concise and to the point. However, it could be slightly more informative about the tool's scope without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 optional parameters and no output schema. The description fails to explain the return format, default filtering behavior (e.g., active=true), or how results are ordered, leaving the agent with incomplete context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents all parameters. The description does not add any additional meaning or context beyond the schema, meeting the baseline but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'Performance Analytics (PA) indicators (KPIs) available in the instance', effectively distinguishing it from sibling tools like get_pa_indicator or create_pa_indicator by specifying the listing 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/5Does 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_pa_indicator for a single KPI or search tools. The description lacks explicit 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and openWorldHint, but the description adds no behavioral context beyond the function name. It does not disclose behavior like pagination, error handling, or potential variability in results, which would be valuable given the openWorldHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is completely free of waste. All words are meaningful and directly contribute to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 operation with good annotations. However, it lacks details about the return format or what constitutes a 'function', leaving some ambiguity for an AI agent. The presence of a limit parameter is implied but not explained in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds no additional meaning beyond the schema, so it meets the baseline but does not compensate for any ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the specific resource 'HTTP methods (functions) defined within a REST Message'. It uniquely identifies the tool's action and differentiates it from sibling tools like list_rest_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool or alternatives is provided. While the purpose is clear, there is no mention of prerequisites, when not to use, or comparison with related 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?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds no extra behavioral info (e.g., pagination, result truncation, or that the limit parameter affects 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 6 words, no fluff, immediately conveys the action and resource. Exceptionally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description does not explain what a field-level mapping is or what the return structure looks like. Adequate for a known concept, but could be more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description repeats the parameter names without adding new meaning. Baseline 3 is appropriate since the schema adequately describes parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'field-level mappings within a Transform Map', clearly differentiating from siblings like 'list_transform_maps' (lists maps) and 'run_transform_map' (executes mappings).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 (e.g., list_transform_maps, run_transform_map). No explicit when, when-not, or alternative tools 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 indicate readOnlyHint=true and openWorldHint=true, so the description adds the behavioral requirement of SCRIPTING_ENABLED=true. However, it does not disclose other aspects like rate limits, pagination details, or impact of not filtering by table. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, very concise with no wasted words. However, it could be front-loaded with the most critical information (e.g., listing what UI actions are) and structured for scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 4 optional parameters, no output schema, and a broad sibling list, the description is minimal. It does not describe what information is returned, default behavior when no table is specified, or how filtering works across the parameters. Leaves significant gaps in understanding the tool's full capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 does not add meaning beyond 'for a table' which maps to the table parameter. The purpose is clear from schema, and description adds no extra semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (list) and resource (UI actions) with examples in parentheses, and specifies the scope (for a table) and a prerequisite (SCRIPTING_ENABLED=true). It is distinct from sibling list tools like list_ui_policies or list_business_rules, though it does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a condition (requires SCRIPTING_ENABLED=true) but no guidance on when to use this tool versus alternatives like list_ui_policies or other list tools. No comparative context 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, indicating a safe, read-only operation. The description adds no additional behavioral context beyond the annotations, which is acceptable but not contributive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is concise and immediately communicates the tool's purpose and optional filter capability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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, the description is minimally adequate. However, it lacks details on result format, pagination behavior beyond limit, and clarification on how the query filter works. Given the absence of an output schema, more context could be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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's mention of 'optional search filter' aligns with the query parameter but does not add new meaning beyond the schema. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List users' as the action, which is a specific verb-resource combination. The 'optional search filter' adds scope. It implicitly distinguishes from siblings like get_user (single user) but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not mention when to use this tool over alternatives like search_tools or get_user, nor does it specify contexts 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, indicating a non-destructive read operation with potentially varying results. The description adds that it returns 'category and status details', which is useful but does not disclose other behaviors such as pagination, response size limits, or how filters interact with results. This is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states what the tool does. It is front-loaded with the main action and resource, with no unnecessary words 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has four optional parameters, no output schema, and annotations providing some behavioral hints, the description is somewhat complete but lacks important context. It does not explain the default behavior when no filters are applied, pagination details, or the response structure. For a listing tool, more information would help the agent use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters have descriptions in the input schema (100% coverage), so the schema effectively documents parameter semantics. The tool description does not add any additional meaning beyond what is already 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('List all Virtual Agent topics') and specifies the included details ('with category and status details'). It uses a specific verb and resource, making the purpose clear. However, it does not differentiate from similar sibling tools like get_virtual_agent_topics or list_va_categories, which could cause 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/5Does 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 lacks information on prerequisites, preferred contexts, or situations where this tool is not suitable. The agent is left to infer usage from the name and schema 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 provide readOnlyHint and openWorldHint, indicating safe, read-only access to a large dataset. The description adds minimal context (module name) but doesn't explain additional behavioral traits like default ordering, pagination limits, or whether filtering is required for large result sets.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence with no wasted words. However, lacks any structural organization (e.g., bullet points or sections) that could improve scanning efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description fails to mention return data format (e.g., list of vulnerability objects) or how parameters interact. For a list tool with 5 optional parameters, this is incomplete guidance for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 5 parameters. The description adds no value 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/5Does 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 'vulnerability entries' from the specific 'Vulnerability Response module', distinguishing it from siblings like 'scan_vulnerabilities' (scan action) and 'get_vulnerability' (single 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 Guidelines2/5Does 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 'scan_vulnerabilities' or 'get_vulnerability'. No mention of prerequisites, context, or when not to use this list operation.
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 it as read-only (readOnlyHint=true) and open-world (openWorldHint=true). The description adds that it returns accuracy, training status, and metrics, but does not reveal additional traits like data freshness or permission requirements. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that effectively communicates the tool's purpose without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description mentions key outputs (accuracy, training status, metrics), it lacks specifics on return format or additional details. Given no output schema, it could be more explicit but is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, model_sys_id, is fully described in the schema ('ML solution sys_id'). The description does not add extra meaning beyond the schema, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 identifies the resource, though it could be more precise about what 'metrics' includes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 ml_model_training_history or ml_predict_change_risk. The description does not differentiate it from sibling ML 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 indicate readOnlyHint=false and destructiveHint=false. The description adds [Write] which is consistent but does not elaborate on side effects, duration, or permissions. Minimal added 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and to the point, with a [Write] tag for clarity. However, it could be expanded slightly to include more context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing information about return values (e.g., job ID, status), prerequisites, or post-trigger behavior. Essential for a write action that starts a process.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; the description does not add meaning to the parameter 'solution_name'. It only restates the function without parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Trigger training' and the resource 'incident classification ML solution', with a [Write] tag indicating it's a write operation. It is distinct from sibling ML tools like ml_auto_categorize or ml_predict_change_risk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 ml_auto_categorize or ml_train_anomaly_detector. Missing context on prerequisites or typical 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?
Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds no extra behavioral context such as response format, error handling, or authentication 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 well-described params, read-only annotations, and no output schema, the description is minimally adequate but lacks details on return structure and potential errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%. The description adds no additional meaning beyond what the schema already provides for question, limit, and table. Baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool takes a natural language question and returns structured ServiceNow data. It references the specific NLQ API, distinguishing it from sibling search tools like natural_language_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 like natural_language_search or query_records. The description does not mention prerequisites or limitations.
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 annotations (readOnlyHint=false, not destructive), the description only adds a prerequisite. It does not disclose side effects (e.g., status change, notifications, approval requirements). For a mutation tool with no output schema, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and includes essential information. Slightly loses points for not using a period or more structured formatting, but still highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a mutation tool with no output schema, the description should specify the effect (e.g., changes article state to published) or return value. It only mentions a prerequisite, leaving the agent to assume behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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. The description adds no extra meaning beyond 'System ID of the article to publish', so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'publish' and resource 'draft knowledge article', distinguishing it from siblings like create_knowledge_article, update_knowledge_article, and retire_knowledge_article. The mention of 'draft' clarifies the input state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description states a prerequisite (WRITE_ENABLED=true) but does not provide guidance on when to use this tool versus alternatives like update_knowledge_article. Usage is implied (to change draft to published) but lacks exclusions or context.
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: readOnlyHint=true while the description says 'write edited fields back' and 'Overwrites the listed fields with NO merge' — a clear write operation contradicts a read-only annotation. openWorldHint=true also conflicts with the explicit requirement of WRITE_ENABLED=true. The description does add good behavioral context (NO merge, abort on conflict) but the contradiction is serious and disqualifies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact three-sentence block that front-loads the core action and key prerequisite (WRITE_ENABLED=true). It includes the critical NO-merge and expected_updated_on conflict behavior in the same sentence, which is dense but efficient. No wasted words, though it could be slightly better structured with the merge behavior separated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex mutation tool with no output schema and a serious annotation contradiction, but the description does cover prerequisites, merge behavior, conflict detection, and both field input modes. It lacks explicit return-value or success/failure contract information, and the openWorldHint with WRITE_ENABLED requirement leaves some ambiguity about environment constraints. Reasonably complete for the complexity but not outstanding given the contradictory annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents all four parameters. The description adds meaningful semantics beyond the schema: it explains the dual meaning of 'fields' (inline vs. on-disk from NOWAIKIT_SYNC_DIR), and gives context on expected_updated_on (aborts with CONFLICT if changed). This exceeds the baseline-3 judgment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Local sync: write edited fields back to an artifact') which distinguishes it from siblings like pull_artifact, sync_status, and find_artifact. It clearly names what the tool does. However, it relies on the tool name to convey much of the purpose, though the mention of 'write edited fields back' and 'Overwrites the listed fields with NO merge' adds useful scoping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this is for the push side of a local sync workflow ('Local sync'), and it correctly references running sync_status first and passing expected_updated_on. It implies usage within a pull-push sync cycle. It doesn't explicitly name alternative tools or when-not-to-use, but the workflow context (requires pull/sync_status first) is actionable 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 provide readOnlyHint=false indicating a write operation. The description adds the requirement WRITE_ENABLED=true, which is helpful context. However, it does not disclose other behavioral traits like state changes, reversibility, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that concisely states the purpose and a key requirement. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool modifies incident state and has 3 required parameters, the description lacks details on prerequisites (e.g., incident must be in a certain state) and what happens after resolution (e.g., state change, notifications). It is minimally adequate but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 simply repeats 'resolution code and notes' without adding meaning beyond the schema. It does not elaborate on valid formats or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 the required inputs. It distinguishes from siblings like close_incident by focusing on resolution, but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('requires WRITE_ENABLED=true') but provides no guidance on when to use this tool versus alternatives like 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds a '[Write]' tag but no additional behavioral context about consequences, reversibility, or required permissions. It is adequate 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, using a single sentence plus a [Write] tag. It is front-loaded and efficient, though the tag is slightly redundant with annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive nature and lack of output schema, the description should explain return values, side effects, or reversibility. The current description is too minimal for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters. The description does not add any extra meaning or examples beyond the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retire') and the resource ('IT asset'), specifying it marks the asset as disposed/retired. This distinguishes it from siblings like 'update_asset' or 'delete_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives. It lacks prerequisites, exclusions, or context for appropriate use.
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 destructiveHint=true and readOnlyHint=false. The description adds a **[Write]** label but does not elaborate on side effects, reversibility, or necessary permissions. Adequate but not enhanced 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise single sentence with a label. Minimal structure but effective. No wasted words, though it could be more organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite destructive hint, description lacks details about post-rollback state, impact on deployment status, or expected outcomes. No output schema provided, so more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 does not add any additional meaning or context for parameters beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Rollback a deployment' and the mechanism 'reverting an update set', with a **[Write]** label for clarity. It distinguishes this tool from siblings like validate_deployment or track_deployment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 validate_deployment or track_deployment. No prerequisites, scenarios, or exclusions 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 write operation (readOnlyHint=false), which the description echoes with '[Write]'. No additional behavioral details beyond this are 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with one sentence and a clear '[Write]' tag. No unnecessary text, but lacks typical structured context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with nested objects and no output schema, the description does not explain return values, side effects, or permission requirements. More context is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and parameters are clearly named and described in the schema. The description adds no new meaning to the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Execute') against a specific resource ('security playbook') and context ('against an incident'). It distinguishes from siblings like execute_playbook by specifying security 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/5Does 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 'execute_playbook' or other security incident tools. No prerequisites or conditions 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 aligns with the 'readOnlyHint' annotation, indicating a read-only operation. However, it does not add any behavioral details beyond what the annotation already provides, such as whether the output is a list or graph.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently communicates the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 adequate but lacks details about the output format or scope (e.g., whether it returns all dependencies or a filtered set). It could benefit from mentioning the nature of the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'service_sys_id' is fully described in the schema as 'System ID of the business service'. The description does not add extra meaning or context, 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: viewing service dependencies and related CIs for impact analysis. It uses a specific verb and resource, but does not explicitly differentiate from the sibling tool 'cmdb_impact_analysis', which may have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 'cmdb_impact_analysis'. The description lacks explicit context on prerequisites or use cases, leaving the agent to infer 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 indicate idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds the WRITE_ENABLED requirement, which is useful context. No contradictions with annotations. The description does not elaborate on other behaviors like return values 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff. It conveys the essential information (action, resource, prerequisite) efficiently. Every word is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (update with two parameters) and no output schema exists. The description provides the prerequisite but lacks details about return values, possible errors, or behavior when fields are invalid. Given the simplicity, it is somewhat complete but could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for its two parameters (sys_id, fields) with clear descriptions. The description does not add any additional parameter semantics beyond what the schema already provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 'scrum task', and adds a prerequisite (WRITE_ENABLED=true). However, it does not differentiate this tool from sibling update tools like update_task or update_story, which have similar names and 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is the WRITE_ENABLED requirement. There is no mention of when to use this tool over alternatives (e.g., for scrum tasks specifically vs generic update_record). No exclusions or context 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 readOnlyHint=false and destructiveHint=false. The description adds the requirement 'WRITE_ENABLED=true', which is a behavioral constraint not in annotations. However, it does not describe side effects or error handling, so only 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous information. It is efficiently front-loaded with the core purpose and a key requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested object parameter, no output schema, annotations present), the description is minimal but covers the basic purpose. It lacks details on partial updates, response behavior, or field validation, making it only slightly above average.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description restates that 'fields' can update state, severity, containment_status etc., but adds no new information beyond the schema. Score is baseline due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a security incident record' with a specific verb and resource. It is distinguishable from siblings like 'update_incident' by the 'security' qualifier, though it could be more explicit about the tool's 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/5Does 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 'update_record' or 'update_incident'. It only mentions a prerequisite condition (WRITE_ENABLED=true) but no context on when to choose this 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, indicating a safe, read-only operation. The description adds context on the specific quality aspects analyzed, which is adequate but does not disclose any additional 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/5Is 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 and scope without any superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description lists the quality aspects, it does not explain the output format or what the result looks like. Given the lack of an output schema, the description should provide more detail on the return value to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are covered in the schema (100% coverage). The description adds value by providing a default value for 'days_stale' and clarifying the format for 'required_fields' as comma-separated, which supplements the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool analyzes data quality for a table, listing three specific aspects: completeness, duplicates, stale records. However, it does not explicitly distinguish itself from sibling tools that focus on one aspect each, such as check_table_completeness or cmdb_find_duplicates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 sibling tools include specialized data quality checks, but the description lacks any comparison or recommendation.
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 indicate a non-read-only, non-idempotent, potentially open-world operation. The description adds only the SCRIPTING_ENABLED prerequisite, but does not explain behavioral traits like side effects, data modification, or failure behavior, which are important for a mutation 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, efficient and directly to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description omits essential context such as what committing does (applies changes), potential impacts, and expected outcomes. Given the tool's potential to modify data, this is insufficient for an agent to use it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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. The description adds no additional meaning beyond the schema, which is adequate but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'commit' and the resource 'update set', distinguishing from siblings like preview_update_set and publish_changeset. It precisely identifies the action and target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the prerequisite SCRIPTING_ENABLED=true, but lacks guidance on when to use commit versus alternatives like preview or publish, and does not specify 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 this is a write operation (readOnlyHint: false). The description adds the permission requirement (WRITE_ENABLED=true), which is valuable behavioral context beyond annotations, though it does not disclose other traits like idempotency 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. Every word is necessary and front-loaded, making it efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite full schema coverage, the description lacks important context: no mention of return value, no guidance on related tools (e.g., get_catalog_item for verification), no mention of typical workflow or prerequisites beyond WRITE_ENABLED. For a tool with 8 parameters, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents all 8 parameters. The description adds no additional meaning or context beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new service catalog item' uses a specific verb and resource, clearly distinguishing it from sibling tools like update_catalog_item, order_catalog_item, and 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only mentions a prerequisite (WRITE_ENABLED=true) but provides no guidance on when to use this tool versus alternatives, such as when to update vs create, or what the catalog item creation implies.
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 prerequisite but discloses no other behavioral traits such as side effects, return values, or error handling. With annotations present, the description provides minimal 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that states the action and a prerequisite. It is front-loaded with the verb and resource, contains no filler, and every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 15 parameters, no output schema, and a complex domain (change management), the description is too brief. It does not explain the purpose of change requests, approval workflows, or what the return value/sys_id will be. The agent lacks critical behavioral context beyond creation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter has a description. The tool description itself adds no parameter-level information beyond the prerequisite. Baseline of 3 is appropriate since the description does not need to repeat schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb-resource combination 'Create a new change request', which distinguishes it from update, close, or get variants among siblings. The prerequisite adds specificity, but no explicit differentiation from other create 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (WRITE_ENABLED=true) but provides no guidance on when to use this tool versus alternatives like create_incident, update_change_request, or other create tools. Usage context is implied by the tool name 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 convey read-only (false), non-destructive, and non-idempotent. The description adds the WRITE_ENABLED requirement, which is useful but does not elaborate on side effects or mutation behaviors beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at one sentence, including a necessary precondition. It is front-loaded and wastes no words, but could be slightly more structured with a brief output note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters and no output schema, the description is incomplete regarding return values. It does not hint at what is returned after creation. For a create tool in a rich domain, this is a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 parameter-level information 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new Customer Service case', specifying the verb and resource. It distinguishes from sibling tools like update_csm_case and close_csm_case. The prerequisite is also noted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (WRITE_ENABLED=true) but provides no guidance on when to use this tool vs alternatives like update_csm_case or close_csm_case. No explicit 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it's a write operation (readOnlyHint=false). The description adds the requirement for WRITE_ENABLED=true, which is beyond annotations, but does not disclose other behavioral traits like 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence front-loads purpose and prerequisite with no extraneous content. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain return values or confirmation behavior. It also lacks details on side effects or post-creation steps, leaving significant gaps for a tool with 8 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented in the schema. The description does not add extra meaning beyond what the schema 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the specific resource 'email notification definition', distinguishing it from other create tools that create different objects. It provides a prerequisite (WRITE_ENABLED=true) that 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives only a prerequisite but lacks guidance on when to use this tool versus alternatives like create_record or other notification tools. No context on when not to use or comparisons 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?
Annotations already indicate this is a write operation (readOnlyHint=false) with possible side effects (openWorldHint=true) and non-destructive. The description adds that it creates 'all standard tasks', implying additional record creations, but does not detail other behaviors like required permissions, potential duplication (idempotentHint=false), or what happens to existing 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence with a tag. It front-loads the core purpose with no wasted words. Every element earns its place, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool having 6 parameters and no output schema, the description is minimal. It does not explain the return value, preconditions (e.g., employee must exist), or fully elaborate on the side effects hinted by openWorldHint=true. The description is insufficient for an agent to fully understand the tool's implications and expected output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 6 parameters are fully described in the input schema (100% coverage), so the description adds no extra parameter-level meaning. The description's mention of 'employee onboarding case' aligns with the schema's employee_sys_id parameter but does not provide additional semantic context beyond what is already documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an 'employee onboarding case with all standard tasks', using a specific verb and resource. It distinguishes from siblings like create_offboarding_case and create_hr_case by specifying the case type and the inclusion of standard tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, nor does it mention any prerequisites or when not to use it. Agents are left to infer usage context 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 readOnlyHint=false, confirming a write operation. The description adds the requirement WRITE_ENABLED=true, which is useful behavioral context. However, it does not cover other traits like idempotency (annotations indicate false) or potential side effects, so it adds modest 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is succinct and to the point, with no unnecessary words. It efficiently conveys the core purpose and a critical requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and no output schema, the description is too brief. It does not explain what a REST Message definition is, the format of the endpoint URL, or what the created message returns. More context is needed for an agent to use it correctly without relying solely on schema labels.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions, so the baseline is 3. The description does not add any additional meaning or context for parameters 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a new outbound REST Message definition. It distinguishes from sibling tools like get_rest_message and list_rest_messages by specifying creation, and includes a prerequisite requirement (WRITE_ENABLED=true).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (WRITE_ENABLED=true) but provides no guidance on when to use this tool versus alternatives, such as create_record or other create tools. There is no discussion of exclusions or context for choosing this over similar 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 indicate readOnlyHint=false and openWorldHint=true. The description adds '[Write]' confirming mutation, consistent with annotations. No additional behavioral details (e.g., side effects, permissions).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence plus a tag). It is front-loaded with the purpose. The '[Write]' tag is redundant but not harmful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 4 parameters and no output schema, the description provides the basic purpose but lacks details on parameter usage, return values, or behavioral context. Adequate but could be more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 4 parameters. The tool description adds no extra meaning beyond what the schema already provides; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a 'new reusable subflow' with a specific verb and resource, distinguishing it from other create tools like 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/5Does 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 (e.g., create_flow, create_agentic_workflow). The description does not mention context, prerequisites, 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 destructiveHint=true and readOnlyHint=false. The description adds '[Write]' which repeats the write nature but adds no new insights about 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence. It is front-loaded and efficient, though it could be slightly expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, the description is minimally adequate. It could mention permanence or that the property must exist to be complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear parameter description. The description adds no meaning beyond the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and resource ('system property'), with the specific criterion ('by name'). It distinguishes from sibling tools like set_system_property and get_system_property.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys when to use (when deletion is needed), but provides no explicit when-not or alternatives. With sibling tools, usage is clear but not elaborated.
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 destructiveHint: true, so the '[Write]' tag adds minimal value. The description does not disclose consequences (e.g., permanent deletion) or any required permissions 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence plus a tag. No filler, front-loaded, 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/5Given 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 covers the essential purpose. However, it lacks usage context to differentiate from sibling delete tools, preventing a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description does not add meaning beyond the schema's 'UIB page sys_id'. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Delete a UI Builder page.' This is specific and distinguishes from sibling tools like delete_record or delete_attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 (e.g., other delete tools) or any prerequisites. The description is minimal and lacks context 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 mark readOnlyHint=true, so description is consistent. Adds context that output is XML, which is useful. However, no disclosure of potential size limits, performance, or return format beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one functional sentence plus a bracketed note. All necessary information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Sufficient for a simple read-only tool with one parameter and no output schema. The note '[Scripting]' hints at intended use. Could be improved by mentioning the XML structure or typical use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the single parameter fully with description 'Update Set sys_id'. Description adds no additional detail beyond schema, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb-resource pair: 'Get the XML export payload for an Update Set'. Differentiates from siblings like get_update_set (which likely returns JSON) by specifying XML export format and migration 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or not use this tool versus alternatives like get_current_update_set or preview_update_set. Only mentions 'as used in migration' which is vague.
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 no further behavioral context (e.g., whether it returns a single record, error handling, or that results may vary). It is consistent but not informative 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous information. It is front-loaded and efficient, though very brief. Would benefit from 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.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (one parameter) and presence of annotations, the description is minimally adequate. However, it does not explain the structure of the result or any nuances like pagination or field availability, which could leave an agent uncertain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, with description 'System ID of the suite result record'. The tool's description does not add extra meaning beyond this, meeting baseline expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the results of a test suite run, using a specific verb and resource. It distinguishes itself from siblings like get_atf_test (which gets a single test) and list_atf_test_results (which lists many).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 such as get_atf_suite or list_atf_test_results. The implied use is when you have a specific suite result sys_id, but the description does not clarify 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 and openWorldHint=true, so the description's statement 'Get details and status' aligns with safe read behavior. The description does not add additional behavioral context beyond annotations, but neither does it 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/5Is 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 unnecessary words. It is front-loaded and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (one required parameter, read-only), the description is adequate. It covers the basic purpose, and annotations cover behavioral aspects. However, it could mention what 'details' include or any limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a description for the 'sys_id' parameter. The tool description does not add any extra meaning or formatting 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.
Purpose4/5Does 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 ('deployment'), specifying 'details and status' which adds specificity. It differentiates from siblings like 'list_deployments' by focusing on a single deployment, but does not explicitly contrast with similar get tools like 'get_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/5Does 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 any prerequisites, exclusions, or scenarios where another tool 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.
- 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's 'Get details' adds no behavioral insight beyond what annotations provide. No additional traits like error handling or access needs 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that is front-loaded and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 explain what fields the 'details' contain. For a single retrieval tool, this omission reduces completeness. Also, no error conditions are mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'name_or_sysid' well-described. The tool description does not add extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get details of a specific registered event definition', using a specific verb and resource, and distinguishes it from siblings like 'list_event_registry' (listing) and 'register_event' (creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 (e.g., 'list_event_registry' for listing or 'register_event' for creating). 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.
- 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 known. Description adds no additional behavioral context beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single clear sentence with no unnecessary words. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and no output schema, the description sufficiently conveys what the tool does and returns (row count and transform status).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter described as 'Import Set sys_id'. Description adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description specifies verb 'Get', resource 'Import Set', and includes specific details like row count and transform status. While clear, it does not explicitly differentiate from siblings like get_record or list_import_sets, but the speciifics help.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 (e.g., list_import_sets for multiple). No when-not-to-use 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 already provide readOnlyHint=true and openWorldHint=true, indicating safe, read-only behavior. The description adds value by specifying the type of analytics (e.g., sessions, active users), but does not disclose how results are aggregated or whether data is real-time. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the tool's purpose. While efficient, it could be slightly improved with structured formatting (e.g., bullet points) for readability. No excess words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a high-level summary of the output (sessions, active users, popular applets), which is helpful given no output schema. However, it omits the time dimension controlled by the 'days' parameter, and does not explain default behavior or data recency. Adequate but incomplete for a full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the sole parameter 'days', so the baseline is 3. The description does not mention the parameter, so it adds no additional meaning beyond the schema. The parameter's role is implied but not clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get mobile app usage analytics') and provides concrete examples of metrics ('sessions, active users, popular applets'), making the tool's purpose unambiguous. It distinguishes itself from sibling tools like 'get_performance_analytics' by specifying 'mobile app' and listing typical mobile analytics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, such as 'get_performance_analytics' or 'get_pa_dashboard'. There is no mention of context, prerequisites, or exclusions, leaving the agent to infer usage without explicit 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 declare readOnlyHint=true and openWorldHint=true. The description adds minimal behavioral context beyond 'get details', lacking information about what details are returned or any side effects. More transparency is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with one sentence. It is efficiently worded but could include a bit more detail without significant bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (single parameter, read-only, no output schema), the description is minimally adequate. However, it does not indicate what 'details' are returned, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'sys_id' described as 'PA job sys_id'. The description adds no additional 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/5Does 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 resource ('Performance Analytics collection job'), which is specific and distinguishes it from sibling tools like 'list_pa_jobs' and other get_* 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/5Does 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. Usage is implied by the name and description, but no exclusions or alternative suggestions 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, setting the safety and variability expectations. The description adds that it returns 'audit history', but does not elaborate on the structure or potential volume of records. With annotations covering the core behavioral traits, 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant information. It is front-loaded with the core purpose, but could benefit from a brief additional sentence on limitations or usage context. It earns a 4 for being efficient though slightly terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is simple (read-only, two parameters, no output schema), the description is minimally adequate. It does not explain what the audit records contain or handle pagination, but the schema covers parameters and annotations set expectations. It is sufficient but not enriched.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description does not add any additional meaning beyond the schema. The baseline of 3 applies as 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get audit history') and the resource ('system property'). The name 'get_property_history' reinforces this. Although it does not explicitly differentiate from siblings like 'get_system_property', the inclusion of 'history' effectively distinguishes it as a historical view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, nor does it mention preconditions or limitations. There is no implicit or explicit indication of 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?
The annotations already declare readOnlyHint and openWorldHint, which cover the safety profile and non-exhaustive nature. The description adds minimal behavioral context beyond the purpose (debugging/auditing). It does not detail any constraints like pagination, limits, or the structure of log entries, but the annotations sufficiently convey behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the purpose. It is appropriately sized for a simple tool with only two optional parameters, and every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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, no output schema) and the presence of annotations that cover read-only and open-world hints, the description is adequately complete. It could mention the open-world hint explicitly, but annotations fulfill that role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters (limit and query) with examples. Since schema coverage is 100%, the description does not need to add parameter information. However, the description also does not provide any additional semantics or context that would aid the agent in using the parameters effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 and identifies the purpose (debugging or auditing). It directly answers what the tool does and for what reason, but it could be more specific about the scope (e.g., system logs from the ServiceNow platform) to fully distinguish from other log tools like 'get_email_log' or 'get_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 Guidelines2/5Does 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 when not to use it or provide context for choosing among sibling tools with similar logging purposes. An effective description would include explicit usage recommendations or contrasts.
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 indicate readOnlyHint=false (write) and openWorldHint=true (side effects). Description adds '[Write]' but fails to disclose potential impacts like overwriting existing records, triggering business rules, or creating update set entries. This is insufficient for a write operation with side effect potential.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient with a single sentence and a tag, front-loading the key action. However, it could benefit from a brief note on expected return or error handling.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of an import operation with no output schema, the description is adequate but lacks details on data format requirements, allowed table values, and error behavior. Schema covers basics, but more context would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for 'data' and 'table'. The description does not add additional meaning beyond what the schema provides. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Import CI data into CMDB via import set' with a specific verb and resource. It distinguishes from sibling tools like create_ci_relationship or cmdb_reconcile by focusing on import set mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for importing CI data but does not explicitly specify when to use this tool versus alternatives like create_record or create_incident. No when-not-to-use or exclusion criteria 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. Description adds the SCRIPTING_ENABLED requirement, which is a useful behavioral constraint. No mention of pagination or default behavior, but within acceptable range.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 18 words, front-loaded with the main action. No wasted words; includes essential prerequisite. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no required params, no output schema), the description covers the core functionality and a key prerequisite. Could mention that it lists all ACLs by default, but still adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description does not add additional meaning beyond the schema, hence baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List Access Control rules (ACLs)' with a brief explanation of ACLs' function. However, it doesn't explicitly distinguish from sibling list tools like list_business_rules, but the resource is specific 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Only mentions a prerequisite (SCRIPTING_ENABLED=true). No guidance on when to use this tool versus alternatives like get_acl or search tools, 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 description adds minimal behavioral insight beyond confirming the tool lists policies and their status. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is concise and front-loaded. Every word serves a purpose, though it could slightly expand on output structure without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 hint at return fields. It mentions 'current status' but could be more explicit. For a simple list tool with annotations, it's adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add any additional meaning to the parameters beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List GRC compliance policies and their current status', using a specific verb and resource. It distinguishes from sibling tools like list_grc_controls and list_grc_risks by focusing on policies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, no mention of filtering or scope. Given the large number of list_* siblings, the description lacks 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 and openWorldHint. The description adds that the tool returns 'deployment history' but does not disclose details like sorting, pagination, or behavior when no parameters are 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the tool's purpose without 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.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 optional params, no output schema), the description provides a basic understanding but lacks details on default behavior, result format, or whether it covers the full historical record. Annotations help compensate for some missing behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 50% of parameters (days has description, limit does not). The description adds no parameter information beyond what is in the schema. It does not clarify the meaning or constraints of 'limit' or how the parameters interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists 'deployment history' and specifies it includes 'committed update sets and app installs over time'. This distinguishes it from sibling tools like 'list_update_sets' (current update sets) and 'list_deployments' (broader deployment info).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or contexts where other 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint: true, openWorldHint: true) already indicate it is a safe read operation. The description adds only the purpose (track sent/failed) without disclosing behavioral traits like pagination, ordering, or result structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. Very concise, though it could be slightly more efficient by combining the verb and purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 fields are returned in the entries. Given low complexity, it is minimally adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all 4 parameters with descriptions (100% coverage). The tool description adds no additional meaning beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'outbound email log entries', specifically to track sent/failed emails. It is distinct from sibling tools like get_email_log or 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 Guidelines2/5Does 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_event_log or get_email_log. The description does not mention scenarios 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, indicating safe, potentially partial results. The description adds no further behavioral context (e.g., pagination, sorting, or return 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that immediately conveys the tool's purpose with a helpful parenthetical. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with annotations and partial schema coverage, the description is minimally adequate but omits details about the limit parameter and any default behavior. An output schema is absent, but the tool is straightforward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% (app_config has a description, limit does not). The tool description does not explain either parameter, failing to compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists mobile applets and defines them as 'mini-apps within the mobile experience'. It distinguishes itself from sibling list tools by targeting a specific resource type not covered by others.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 vs alternatives. There is no mention of prerequisites, context, or scenarios where this tool is appropriate.
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, indicating it's a read operation with possibly incomplete results. The description adds the table name but no further behavioral traits like pagination. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundant information. It is concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with good annotations and full schema, the description is adequate. It identifies the table and purpose. However, it could mention that it returns a list of notification definitions, which improves clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 does not add any meaning beyond what the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List email notification definitions (sysevent_email_action)', specifying the verb and resource. It distinguishes from 'get_notification' which retrieves a single item, but does not explicitly differentiate from 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 Guidelines2/5Does 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_notification' for a single notification or 'list_notification_subscriptions' for subscriptions. The description lacks explicit 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's minimal statement adds little behavioral context. It does not disclose returns, pagination, or potential performance implications 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is concise but arguably under-specified. It earns its place but could include more useful information without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with annotations and a clear schema, the description is mostly complete. However, it doesn't mention the return format or pagination, which would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all three parameters described. The description adds no 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List pages that belong to a Service Portal' clearly states the verb (List), resource (pages), and scope (belonging to a portal). It distinguishes from sibling tools like list_portals, list_portal_themes, 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/5Does 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, no exclusions, and no context on prerequisites (though the required parameter portal_sys_id is implicit). Sibling tools include many list operations without differentiation.
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 (readOnlyHint: true). The description adds the API endpoint indicator ('/api/now/reporting') but does not disclose behavioral details like pagination or search semantics, which are already 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no waste. The description is front-loaded with the primary action and resource, efficiently conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a straightforward purpose with good schema coverage and annotations. The description is adequate for a list operation, though it lacks mention of response format or pagination behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have descriptions in the input schema (100% coverage). The tool description adds zero parameter information 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'saved reports', making the purpose unambiguous. However, it does not explicitly differentiate from sibling list tools like list_acls or list_business_rules, though the resource type is distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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_report (single report), generate_report, or export_report_data. The description lacks usage context or prerequisites.
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 does not add behavioral context beyond the annotations (readOnlyHint=true, openWorldHint=true). It fails to mention pagination, performance implications, or that it returns a list of system property objects. The annotations already cover safety, so the description misses an opportunity to add 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It front-loads the purpose. However, it could be slightly more detailed without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with 4 optional filters and no output schema, the description is adequate but incomplete. It does not mention the return format (e.g., array of property objects) or the default limit of 50 (implied by schema but not described). Given the lack of output schema, 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/5Does 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 4 parameters. The description only says 'with optional filtering', which is generic and 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List system properties' with optional filtering, specifying the verb ('List') and resource ('system properties'). It distinguishes itself from sibling tools like 'search_system_properties' and 'get_system_property' by implying a broad listing of all 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions optional filtering but does not explicitly state when to use this tool versus alternatives like 'search_system_properties' or 'export_properties'. There is no guidance on use cases or exclusions, leaving the agent to infer based on 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=true and openWorldHint=true, so the description doesn't add further behavioral context. It doesn't mention pagination, default limit, or ordering. With annotations, 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Could be slightly expanded to include scope (e.g., 'all') or usage notes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with good annotations and no output schema, the description is adequate but lacks details like default limit behavior or ordering. Completeness is moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters (limit, query). The description adds no additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'Next Experience (UI Builder) applications', making the purpose unambiguous. It distinguishes from sibling tools like list_ux_pages which list pages, not applications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 (e.g., when to use list_ux_apps vs list_ux_pages or search tools). No context on prerequisites or typical 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. The description adds the behavioral trait 'recent', but does not define what 'recent' means (e.g., time window, default ordering). No other behavioral aspects are disclosed 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. However, it could be slightly expanded to mention the default limit or ordering without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with optional filters and no output schema, the description provides the core purpose but lacks details on result ordering, default limit, and what 'recent' entails. The schema covers parameters, but the description could better set expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are fully described in the schema (100% coverage), so the description does not need to add param details. It adds no additional meaning or usage context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List recent Virtual Agent conversations' clearly states the action (list) and the resource (Virtual Agent conversations), with the scope 'recent'. It distinguishes from sibling tools like get_va_conversation, list_va_categories, and list_va_topics_full.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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_va_conversation (for a single conversation) or list_va_topics_full (for topics). The context signals show many sibling list tools, but the description offers no differentiation clues.
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 that. The description adds the 'predict' nature, but no further behavioral traits (e.g., dependency on a trained model, error conditions). 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the tool's function. No unnecessary words, and it is front-loaded with the key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 clarify what the returned risk level looks like (e.g., string, number, structure). It also does not clarify that all parameters are optional but likely need at least one to produce a meaningful prediction. The description is insufficient for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for all three parameters (type, category, change_sys_id). The description does not add extra meaning or constraints beyond what the schema already states. 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: predicting the risk level of a change request using historical ML analysis. The verb 'predict' and resource 'risk level of a change request' are specific, and it distinguishes from similar ML tools like 'ml_train_change_risk' which focuses on training.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No information on when to use this tool versus alternatives. Among siblings, there are training and other ML tools, but the description does not provide guidance on selection criteria or context. It implicitly assumes the user knows when to call prediction.
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 provide readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds no further behavioral context beyond stating it switches instances, which is already implied by the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words. Perfectly 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with one parameter and clear annotations; the description is sufficient for its purpose. No output schema needed, but could mention side effects like session change.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description already covers the parameter 'name' with examples. The description adds no additional meaning beyond the schema, meeting the baseline for 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Switch' and resource 'active ServiceNow instance', clearly indicating the action. However, it does not differentiate from sibling tools like get_current_instance or list_instances, which could cause 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/5Does 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 checking the current instance first or listing available instances. Lacks prerequisites or context for 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?
Annotations already indicate it is a non-read, non-destructive, idempotent write operation. The description adds the WRITE_ENABLED requirement, a useful behavioral constraint. However, it lacks details on side effects, success/failure indicators, or triggers (e.g., approvals).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, highly concise, and front-loaded with the action and resource. No superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only 2 parameters and no output schema, the description is incomplete. It does not explain what fields can be updated, constraints, or response behavior. For a mutation tool, more context is needed, especially given the broad sibling set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add any extra meaning beyond the schema for the sys_id or fields parameters. No valid field keys or formats are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update fields on a change request', specifying the verb and resource. It distinguishes from create and close siblings but not from generic update_record. The purpose is clear but 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('requires WRITE_ENABLED=true'), which gives limited context. However, it does not specify when to use this tool over alternatives like update_record or other update tools, leaving usage guidance 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 safe read (readOnlyHint=true) and open-ended queries (openWorldHint=true). The description adds 'AI-powered' context, implying model invocations with potential latency or cost, but does not disclose rate limits, authentication needs, or error behavior. With annotations covering core safety, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the tool's purpose and scope. Every word adds value without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (3 params, no output schema, good annotations), the description covers the high-level purpose and sources. However, it lacks details on return structure, result format, or pagination. It is 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described (query, sources, limit). The description does not add any additional meaning or constraints beyond what the schema provides. Therefore, it meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'semantic AI-powered search' across specified sources (KB, catalog, incidents). It distinguishes from sibling tools like 'search_catalog' and 'search_knowledge' by being AI-powered and multi-source, leaving no ambiguity about 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 Guidelines2/5Does 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 similar ones like 'search_catalog' or 'search_knowledge'. It lacks explicit context on preferred usage scenarios or exclusions, leaving the agent to infer 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.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, but description and schema include methods like POST, PATCH, DELETE which modify data. This is a clear contradiction, making the description misleading about the tool's mutability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no fluff: purpose, benefit, constraint. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers purpose and constraints, but lacks behavioral disclosure beyond annotations, and no mention of response format or error handling. The contradiction further reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter description. Description adds no extra information beyond 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/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool performs multiple REST API operations in a single call, distinguishing it from individual operation tools in siblings. Verb 'execute' and resource 'ServiceNow REST API operations' are 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions reduction of round-trips by 50-70% implying efficiency use case, and limits max 50 operations. However, does not explicitly state when not to use or compare with alternatives like individual calls.
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 (safe read) and openWorldHint=true (results may change). The description adds that the tool finds stale, operational CIs. While this adds some context, there is no additional disclosure of behavioral traits like pagination or performance implications. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-constructed sentence that conveys all necessary information without any superfluous content. It is front-loaded and uses precise language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core functionality but does not explain the output format, pagination behavior, or what happens if no stale CIs are found. Given the simple nature of the tool and the presence of annotations, this 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have descriptions in the input schema (100% coverage). The tool description does not add any additional meaning or context beyond what the schema already provides. Baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Find', the resource 'CIs', and the specific criteria (not updated within a given number of days and still operational). It effectively distinguishes from sibling tools like cmdb_find_duplicates and cmdb_find_orphans.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, nor does it mention any prerequisites or limitations. It merely describes what the tool does without context about appropriate usage 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 indicate readOnly=false, destructiveHint=false, openWorldHint=true, idempotentHint=false. The description adds the WRITE_ENABLED requirement, which is useful but does not elaborate on side effects, error cases, or output behavior. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence conveying purpose and a key condition. No unnecessary words or tangents. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the purpose is clear, the description omits the expected return value (since no output schema), assumes understanding of 'WRITE_ENABLED', and doesn't explain prerequisites for the parameters. Could be more complete given the lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are well-documented. The tool description does not add any parameter-specific details beyond what the schema 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/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Create a new Performance Analytics dashboard' with a specific verb and resource, and includes a prerequisite condition (WRITE_ENABLED=true). This distinguishes it from sibling tools like create_pa_indicator or update_dashboard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 (e.g., update_dashboard, create_pa_breakdown). The only context is the WRITE_ENABLED prerequisite, which is a condition but not explicit 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 indicate readOnlyHint=false (not read-only) and destructiveHint=false, so the agent knows it's a mutation without destruction. The description adds the precondition 'requires WRITE_ENABLED=true', which is valuable beyond annotations. However, it does not disclose return behavior, error cases, 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.
Conciseness4/5Is 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 key requirement. It is concise and contains no unnecessary information. However, it could be slightly expanded to include more usage guidance without loss of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having annotations and a high schema coverage, the description is very brief. For a creation tool with no output schema, it lacks information about the return value, confirmation of success, or any side effects. The agent has insufficient context to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all parameters described in the schema. The description does not add any additional meaning to the parameters beyond what the schema provides. Thus, it meets the baseline but does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create a new page inside a Service Portal', specifying the verb 'Create' and the resource 'page inside a Service Portal'. It distinguishes from sibling tools like create_portal (creates the portal itself) and create_portal_widget (creates widgets). The requirement 'WRITE_ENABLED=true' 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (WRITE_ENABLED=true), which guides when the tool can be used. However, it does not explicitly state when to use this tool versus alternatives like create_portal or create_portal_widget, nor does it provide exclusions or context about what the created page is used for.
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', which implies a write operation consistent with annotations (readOnlyHint=false). However, it does not disclose other behaviors such as side effects, error conditions, or return format. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the purpose and a key prerequisite. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters and no output schema, the description provides minimal context beyond the prerequisite. It does not explain the response upon creation or any follow-up actions. The schema is detailed, but for a creation tool, agents might benefit from knowing what to expect (e.g., job ID).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already describes all parameters. The description does not add any additional meaning beyond the schema, such as parameter constraints or relationships. Baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'scheduled script execution job', with an additional prerequisite condition (WRITE_ENABLED=true). It distinguishes itself from other 'create_*' siblings by specifying the scheduled script execution nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only mentions a prerequisite condition (WRITE_ENABLED=true) but does not provide context on when to use this tool versus alternatives or when not to use it. No comparison with sibling tools or 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 indicate non-read-only and non-destructive behavior. The description adds the scripting requirement as a behavioral context, but does not disclose other behaviors like side effects 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the primary purpose and adds the key prerequisite without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the core purpose and a prerequisite, it lacks context about the return value (no output schema) and differentiation from similar tools. With 9 parameters, more contextual guidance on parameter roles could be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema. The tool description does not add additional meaning or context for the parameters beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it creates a UI action (button/link) on a form, with a specific prerequisite. However, it does not differentiate from related sibling tools like create_ui_policy or 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes a key requirement (SCRIPTING_ENABLED=true) which serves as a usage guideline, but lacks guidance on when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, making the read nature clear. The description adds no additional behavioral context (e.g., return format, sorting, pagination).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, efficiently conveying the tool's purpose without any unnecessary words. It is well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description explains what the tool does, it lacks details about the structure of the activity log or any limitations. With no output schema, a bit more context would help the agent understand the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a description for the one parameter (hr_case_sysid). The tool description does not add further meaning beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 activity log and journal entries for an HR case', distinguishing it from sibling tools like get_hr_case (basic case details) and get_hr_lifecycle_events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case (retrieving activity logs) but does not explicitly state when to use this tool versus alternatives, nor does it mention 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.
- 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. The description adds context that it retrieves 'definition and metadata', but does not disclose any behavioral nuances like error scenarios or output 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded and contains no extraneous information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 is minimal. However, it does not explain what constitutes 'definition and metadata' or the expected return format, which could help the agent understand the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—the input schema already documents the parameter clearly ('Report sys_id or exact name'). The description adds no further semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'saved report', clearly stating it retrieves 'definition and metadata'. This distinguishes it from sibling tools like list_reports (list) and create_report/update_report (write 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/5Does 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_reports or get_report for a different purpose. The description does not specify prerequisites or exclusions, 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, indicating a safe read operation. The description adds no further behavioral context (e.g., what happens if sys_id_or_name is invalid, what 'configuration details' includes). 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and object, no extraneous words. Highly concise and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is simple (1 param, no output schema), the description is adequate but misses the opportunity to explain what 'configuration details' includes (e.g., name, version, settings). With no output schema, additional context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with param 'sys_id_or_name' described as 'App sys_id or name'. The description adds no additional meaning or constraint beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 details of a Next Experience application', making the tool's purpose immediately evident. It is specific enough to distinguish from other 'get_*' tools (e.g., get_scoped_app) by targeting exactly 'ux_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/5Does 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_scoped_app or list_ux_apps. No mention of prerequisites, context, or when not to use it. The description provides no usage 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?
The description aligns with annotations (readOnlyHint=true) and adds no contradictory information. However, it does not elaborate on potential behavioral nuances like result ordering, pagination behavior beyond the limit parameter, or that it filters by active accounts by default. Annotations already declare safety, so a minimal description is acceptable 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is appropriately front-loaded with the action and resource. Every word adds value; there is no wasted text. It is concise and effective for a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 optional parameters, no output schema, readOnlyHint), the description is minimally adequate. It does not describe the return format or any constraints beyond what the schema provides, but for a list operation with good annotations, this is sufficient but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with clear descriptions (limit, query, active). The description only mentions 'optional search filter' which is covered by the schema. With 100% schema description coverage, the baseline is 3; the description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 ('customer accounts'), and mentions the optional search filter, which distinguishes it from sibling tools like get_csm_account (singular) and other list tools for different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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., search_csm_accounts or more specific list tools). It does not mention that it defaults to active accounts or that the query filter is name-based.
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 safe read and varied results. Description aligns but adds minimal extra behavioral context (e.g., no mention of pagination or sorting).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action and resource, no unnecessary words. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description is adequate for a simple list tool with good annotations and no output schema. However, it lacks details on default behavior (like limit default of 50) or return format, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions (100% coverage). The tool description does not add parameter meaning beyond 'search products by name' and 'limit' which are already in schema. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'List' and identifies the resource as 'products and services available in the CSM catalog', clearly distinguishing it from other list_* 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 Guidelines2/5Does 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 list_csm_cases or other catalog tools. The description does not provide contextual usage 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. The description adds 'recent' which suggests a time-based filter but is vague. No additional behavioral context like pagination or default sorting 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at six words, front-loading the core functionality. 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.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not explain return values. It mentions 'recent' but not default behavior. The parameters are well-documented in the schema, but overall completeness is adequate for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all four parameters. The tool description does not add any extra 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as listing recent application deployments in ServiceNow, using a specific verb and resource. However, it does not distinguish from sibling tools like list_deployment_history or list_instances, which could cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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. The description implies a general listing scenario, but given many similar list tools, it would benefit from clarifying when list_deployments is preferred over 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 declare readOnlyHint and openWorldHint, but the description adds no behavioral context (e.g., default limit, pagination, or that active filter defaults to true). Minimal 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence with no unnecessary words or repetition. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Basic description adequate for a simple list tool with good annotations. Missing details on pagination or default limit, but not severely incomplete given low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions (100% coverage). Description does not add meaning beyond the schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb (list) and resource (DevOps pipeline configurations), and scope (registered in ServiceNow). Distinguishes from siblings that list other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 list_deployments or get_devops_pipeline. No exclusion criteria or context 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=true and openWorldHint=true, so the description's addition that it lists templates 'used by notifications' adds minimal behavioral context. No contradictions. Lacks details on pagination or ordering 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no redundant words, efficiently conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 adequate but does not explain output format, sorting, or default limit. It fulfills basic needs but leaves some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters (limit and query). The description does not add any further 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/5Does 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 templates', making the tool's purpose specific and distinguishable from sibling tools like 'list_notifications' which lists notifications themselves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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_notifications' or other list tools. The description does not specify 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 provide readOnlyHint and openWorldHint. The description adds no further behavioral context (e.g., performance, authorization needs, or side effects). The filters are mentioned but don't deepen 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/5Is 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 filter options.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 adequate. However, it omits the return format or pagination details, which could be helpful for the agent. The limit parameter hints at pagination but isn't explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the three parameters. The description repeats 'optional project or state filter' without adding new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'epics', and mentions optional filters (project or state), making the tool's specific function immediately clear. It distinguishes itself from other list tools by specifying the exact resource and filter options.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 sibling list tools (e.g., list_stories, list_assets) or when not to use it. No context about prerequisites or alternatives 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 readOnlyHint=true and openWorldHint=true. The description adds the scope 'Process Automation Designer' but does not disclose further behavioral traits like default filtering (active=true) or pagination behavior. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the essential purpose with no wasted words. It is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only optional parameters and no output schema, the description is adequate but minimal. It does not explain the return format or behavior when no results are found, though the annotations and schema provide reasonable context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter (limit, query, active) is already described in the input schema. The description adds no additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Process Automation Designer playbooks and processes' clearly specifies the verb ('List'), resource ('Process Automation Designer playbooks and processes'), and distinguishes from sibling tools like list_playbooks (which lists only playbooks) and list_flows (which lists flows).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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_playbooks, list_flows, or list_subflows. The description does not provide context for selecting this tool over 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 already indicate readOnlyHint=true and openWorldHint=true. The description adds no new behavioral details (e.g., pagination behavior, sorting, or what 'open world' entails). It only restates the basic purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is 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 key information immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and only three optional parameters, the description lacks information about what the tool returns (e.g., fields of the listed apps) or default behavior. It is functionally adequate but minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning each parameter's description is already informative. The tool description does not add additional semantics beyond the schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'scoped applications (custom apps)' installed in the instance. It distinguishes this tool from sibling list tools by specifying a particular app 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/5Does 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 context, prerequisites, or exclusions, 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 declare readOnlyHint=true and openWorldHint=true, so the description carries a lower burden. The description adds no additional behavioral context beyond what annotations imply. It does not mention pagination, default ordering, or rate limits, but these are less critical for a read-only list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise single sentence that front-loads the verb and resource. It is efficient but could be slightly more informative without harming conciseness. Overall, it is well-structured and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 optional parameters, no output schema, and annotations covering read-only behavior), the description is reasonably complete. It covers the essential purpose and filtering capability. However, it could mention the return format (list of task objects) or default behavior (e.g., ordering), but these are not critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 mentions 'optionally filtered by story', which aligns with the story_sys_id parameter, but does not add meaning beyond what the schema already provides for any parameter. No extra semantic value is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'scrum tasks', and specifies an optional filter 'by story'. This distinguishes it from siblings like list_stories (which lists stories, not tasks) and list_my_tasks (which is user-specific). 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 Guidelines2/5Does 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. For instance, it doesn't explain that this tool is for scrum tasks specifically, as opposed to list_my_tasks or list_stories. There is no mention of prerequisites, context, 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.
- 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 reiterate these. It adds no extra behavioral details beyond what annotations provide. A score of 3 is appropriate as the description does not contradict but also does not enhance 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the core action. Every word is essential, and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimally sufficient for a list tool with read-only annotations, but it lacks details about the return format, pagination behavior, or what fields are included for each playbook. More context would improve usefulness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and all parameters have descriptions. The tool description does not add any additional meaning beyond the schema, so 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List available security response playbooks' uses a specific verb ('list') and resource ('security response playbooks'), clearly distinguishing it from the sibling tool 'list_playbooks' which likely lists all playbooks. This specificity helps an agent select the correct 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/5Does 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_playbooks' or 'execute_playbook'. There is no mention of prerequisites, filters, or scenarios, leaving the agent without context for proper 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?
The description adds that stories are listed and filters are optional, which is consistent with annotations (readOnlyHint=true, openWorldHint=true). However, it does not disclose behavioral details like pagination or default ordering beyond what annotations indicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief and lacks structure. While concise, it could be slightly more informative without becoming verbose. Every sentence is earned, but there is room to add clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and presence of annotations, the description adequately covers its purpose and filters. However, it omits details like pagination, sorting, and description of the return format, which would be helpful for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds minimal extra meaning by mentioning 'optional sprint or state filter', but this does not significantly enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists agile stories and mentions optional sprint or state filters. It is specific and distinguishes from sibling list tools like list_epics or list_scrum_tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use filters but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. Usage guidance is implied but not comprehensive.
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-only operation. The description confirms it lists pages but does not add behavioral details beyond what annotations imply, such as whether it returns all pages without a filter or the structure of the response. Given annotations, the description is adequate but adds minimal 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/5Is 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 'List'. It contains no unnecessary words or repetition, making it both concise and easily scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 states the core function and the inclusion of route configurations, but it does not describe the return format or fields, which would help the agent understand the output structure. For a basic list tool, this is 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, both parameters (app and limit) are already documented with clear meanings. The tool description does not elaborate on how these parameters affect the listing (e.g., default behavior when app is omitted or how limit applies). It adds no new semantic value beyond the schema, so it meets the baseline but does not improve upon it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List UI Builder pages and their route configurations' clearly states the verb 'List' and the resource 'UI Builder pages', and distinguishes this tool from siblings like get_uib_page (singular) and list_uib_components (different resource). The addition of 'and their route configurations' specifies the scope of the list, making the purpose 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/5Does 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_uib_page for a specific page or other list tools for different resources. There is no mention of context, prerequisites, or exclusion criteria, leaving the agent to infer usage solely from the tool name and sibling list.
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. The description adds no new behavioral information beyond what is already in the schema (state filter). No mention of pagination, sorting, or result characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no unnecessary words. It is efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output schema and description of return format. For a simple list tool with 3 optional params, it is minimally adequate but could mention pagination or result fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description repeats the state parameter's purpose but adds no new meaning beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'Update Sets', and specifies the key filtering dimension 'by state' with enumerated values, making it distinct from 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/5Does 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 (e.g., list_changesets). While the purpose is clear, it does not explain 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=true and openWorldHint=true. The description adds that it uses analysis of task durations and reassignment patterns, which gives some method insight but does not disclose output format or potential performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded and concise. Every word adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an ML tool with no output schema, the description lacks details about return format or how to interpret results. It gives the analysis method but is not fully self-contained. Sibling differentiation is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The tool description adds no additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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', clearly distinguishing it from sibling tools like ml_detect_anomalies or ml_forecast_incidents. It conveys 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 Guidelines2/5Does 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 (e.g., ml_detect_anomalies, ml_forecast_incidents). Missing context about 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 it is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the requirement WRITE_ENABLED=true, which aligns, but does not explain ordering implications or side effects beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is 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 requirement. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers basic purpose and a requirement but lacks context on ordering process, output, or relationship to catalog items. With no output schema, more context would help, but the schema covers parameters well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 parameters. The tool description adds no additional parameter meaning beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Order') and the resource ('a service catalog item'). It is specific and distinguishes from siblings like create_catalog_item or 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only mentions a prerequisite (WRITE_ENABLED=true) but does not provide guidance on when to use this tool versus alternatives such as create_catalog_item or search_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 indicate non-read-only, non-destructive, and open-world behavior. The description adds the prerequisite condition but does not disclose execution details such as synchronous/asynchronous nature, error handling, or output behavior. Some context is added but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no superfluous words. It includes essential information (action, resource, prerequisite) in a front-loaded manner. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter and no output schema, the description is fairly complete but omits what the tool returns (e.g., success/failure, result ID). The prerequisite is noted, but the agent lacks information about the execution outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'sys_id', which is described in the schema. The description adds no additional meaning beyond the schema, meeting the baseline but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Execute') and the resource ('ATF test suite') with a specific verb. It distinguishes from the sibling 'run_atf_test' by naming the resource as 'suite' rather than 'test', though it does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('requires ATF_ENABLED=true'), which helps usage, but it provides no guidance on when to use this tool versus alternatives like 'run_atf_test'. No explicit when-not 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?
Annotations already indicate the tool is not read-only and not destructive. The description adds the prerequisite condition 'requires ATF_ENABLED=true', which is useful but does not disclose deeper behavioral traits like side effects or result 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that clearly states the action and a prerequisite. No unnecessary words, front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic action and a prerequisite but does not hint at post-execution steps like retrieving test results. Given the simple single-parameter tool, it is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter (sys_id) with 'System ID of the test'. The description adds no further parameter semantics, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 as 'ATF test'. It distinguishes from sibling tools like 'list_atf_tests' and 'get_atf_test', and adds a prerequisite condition for clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 'run_atf_suite'. It only mentions a prerequisite condition, but lacks comparative 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 a write operation (readOnlyHint=false), and the description adds the context of 'future delivery', which implies it is not immediate. However, it does not disclose potential side effects, such as whether it replaces an existing schedule or requires specific permissions. This adds some but not extensive 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence, front-loading the key action and resource. Every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the parameters and lack of output schema, the description covers the basic purpose but lacks usage guidelines and behavioral details. It could be more complete by explaining that it schedules a notification for an existing rule using the provided notification_id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented in the schema. The description adds no additional meaning to the parameters, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Schedule' and the resource 'notification', making it clear that this tool is for scheduling a notification for future delivery. It distinguishes itself from siblings like 'create_notification' and 'update_notification' by focusing on the scheduling aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 'create_notification' or 'update_notification'. It does not mention any prerequisites or context for use.
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, indicating safe read and volatile results. The description adds no further behavioral context (e.g., pagination, result format). Baseline 3 as annotations carry 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, no unnecessary words. Efficient and direct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with good annotations, the description is adequate but could be improved by noting when to prefer this over other search siblings like natural_language_search. Lacks completeness for context among many similar tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description restates 'keyword' which aligns with query, but adds no additional meaning beyond the schema. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches the service catalog for items matching a keyword. It uses a specific verb (Search) and resource (service catalog), distinguishing it from sibling tools like search_cmdb_ci or search_knowledge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 natural_language_search or ai_search. Missing context for when-not-to-use and no comparison to sibling search 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 indicate non-readonly (readOnlyHint=false), non-destructive (destructiveHint=false), and idempotent (idempotentHint=true). The description adds the '[Scripting]' tag, which is minor extra behavioral context. No additional side effects or state changes are described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a note, front-loaded with the action. Every word is necessary and no extraneous information is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter, annotations present, and no output schema. The description is minimal but covers the basic purpose. However, it lacks explanation of what 'active Update Set context' means and could benefit from usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a description for the single 'sys_id' parameter. The tool description adds no extra meaning beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Switch the active Update Set context') and the resource ('to a specified Update Set'). It is specific and distinguishes from sibling tools like 'get_current_update_set' or 'ensure_active_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 Guidelines2/5Does 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 are any prerequisites or conditions mentioned. This leaves the agent without context on proper 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?
Annotations already indicate read/write (readOnlyHint=false) and idempotence (idempotentHint=true). The description adds the requirement for WRITE_ENABLED=true. However, it does not disclose other behaviors like partial vs. full update, error 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence with a parenthetical requirement. It is front-loaded with the action and resource, covering essential information without any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not explain the return value or state changes after update. It is adequate for a simple mutation tool but could benefit from mentioning what the tool returns or any side effects beyond the WRITE_ENABLED precondition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full 100% coverage with descriptions for both parameters (sys_id and fields). The description redundantly says 'update fields' but adds no new semantic information beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update fields) and the resource (existing CSM case). It distinguishes from sibling tools like close_csm_case and get_csm_case by specifying 'update fields' and the requirement parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a precondition (WRITE_ENABLED=true) but offers no explicit guidance on when to use this tool versus alternatives such as update_record or close_csm_case. No 'when not to use' or alternative tool references are included.
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 the specific table 'cmdb_rel_ci' and clarifies the scope but does not elaborate on behavior like performance, pagination, or result format. It neither contradicts nor significantly extends 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the core function without unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple query tool with no output schema, the description suffices. It explains the purpose and scope. However, it could mention that results are a list of CIs, though not critical. Annotations handle partial results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage for both parameters with descriptions. The tool description does not add any parameter details beyond the schema. Baseline 3 is appropriate since schema does the full job.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds CIs with no relationships, using specific verb 'find' and resource 'CIs with no relationships in cmdb_rel_ci'. It distinguishes from sibling tools like cmdb_find_duplicates and cmdb_find_stale by specifying orphaned CIs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 context, exclusions, or when not to use it. Given many sibling CMDB tools, this is a 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 indicate it's a write operation (readOnlyHint=false) and not destructive. The description's '[Write]' prefix aligns but adds no additional behavioral context such as potential duplicate key errors 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at one sentence with a clear prefix. It is front-loaded and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing important context: no mention of return values (e.g., the created variable's sys_id), no guidance that the catalog item must exist, and no behavioral details for error cases. The description is inadequate for a tool with 6 parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 6 parameters are fully documented in the input schema (100% coverage). The description does not add any extra 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add') and the resource ('form variable to a service catalog item'). The '[Write]' prefix reinforces the operation type. It distinguishes from sibling tools like 'create_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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to add a variable to a catalog item) but provides no explicit guidance on alternatives or prerequisites. It does not mention that the catalog item must exist or suggest using 'create_catalog_item' for creating the item 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 write op and not destructive. Description adds the WRITE_ENABLED requirement, which is useful context beyond annotations, but doesn't disclose other behaviors like side effects or returned 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a parenthetical, no wasted words, and the key action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 100% schema coverage and no output schema, the description adds a useful prerequisite. It could further explain what a 'Service Portal configuration' includes to be fully complete, but it's adequate for a simple create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The tool description adds no additional parameter meaning beyond what's already in the schema, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Create' and resource 'Service Portal configuration', clearly distinguishing from siblings like create_portal_page and create_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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Only mentions a prerequisite (WRITE_ENABLED=true) but provides no guidance on when to use this tool versus alternatives like create_portal_page 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.
- 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. The description adds that it registers a route, which is a behavioral detail. However, it does not disclose potential side effects (e.g., required permissions or interactions with other records), which might be important given openWorldHint true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, with only two pieces of information. It is front-loaded and contains no unnecessary words. It could be slightly more informative, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and annotations that indicate it is a write operation, the description is minimal but adequate. It covers the basic function but does not explain the route registration process or what happens after creation. It could be more complete for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so baseline is 3. The description does not add any additional meaning beyond what the schema provides for each parameter. For example, path and title are self-explanatory, and layout's default value is already documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a UI Builder page and registers a route. While the verb 'Create' is implicit from the name, the addition of 'with route registration' adds specificity and distinguishes it from other page creation tools like create_portal_page or create_ux_app_route.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description describes what the tool does but does not provide any guidance on when to use it versus alternative tools such as create_uib_component or update_uib_page. No usage context or exclusions 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 the tool is not read-only, not idempotent, and not destructive. The description adds the requirement for WRITE_ENABLED, which is useful but minimal. It does not disclose other behaviors like duplicate handling or return values, so it carries part of the burden but not fully.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that includes the core purpose and a key prerequisite. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, 4 required, no output schema, and annotations that are basic, the description is too sparse. It does not explain error conditions, success behavior, or what happens on duplicate usernames, which is important for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all parameters described in the schema. The description does not add any meaning beyond what the schema provides, so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new user account, a specific verb and resource. It distinguishes from sibling create tools that target different entities (incident, group, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite condition (WRITE_ENABLED=true) but does not provide guidance on when to use this tool versus alternatives, nor when not to use it. It is adequate but lacks explicit 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?
The description reveals conditional behavior: creation only when no active update set is in progress. This adds context beyond annotations (idempotentHint=true) by explaining the triggering condition. Annotations are consistent; 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—one sentence plus a tag. It front-loads the core action ('Ensure an active Update Set exists') and contains no superfluous information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should inform the agent about return values (e.g., the active update set ID). It does not mention what the tool returns, leaving a significant gap for a tool that likely provides a result. This incompleteness impacts usability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter, with a clear default and purpose. The tool description does not add further meaning beyond what is in the schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: ensuring an active Update Set exists and creating one if needed. It uses specific verbs 'ensure' and 'create' and distinguishes from sibling tools like 'create_update_set' (which always creates) and 'switch_update_set' (which switches to an existing one).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'create_update_set' or 'switch_update_set'. The description does not mention context or exclusion criteria, leaving the agent to infer without explicit 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 provide readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value by explaining the tool behaves as a lookup/pre-flight check on update set state. However, it doesn't disclose return format, whether partial name matching is exact or fuzzy behavior, or pagination/large result behavior. With annotations covering safety, 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the primary purpose and appends the practical rationale. There is zero waste. It's slightly verbose in the rationale clause but that clause adds genuine value in explaining the use context, so it earns its keep.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only lookup tool with 100% schema coverage and both readOnlyHint and openWorldHint annotations, the description is reasonably complete. It explains the matching semantics (partial name), the purpose (promotion pre-flight), and the resource scope (update sets). The 'limit' parameter implications could be clearer (what happens when scanning is exceeded), but this is a minor gap for a low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters ('name' for artifact matching, 'limit' for max scan). The description adds the semantic framing that name supports 'partial' matching and that the tool scans captured updates, which somewhat complements the schema. But the description doesn't add material new meaning beyond what the schema states, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource ('List the update sets that contain changes to an artifact by name') and adds purpose context ('so you know what is in-flight or already captured for promotion before you touch it'). It distinguishes from sibling tools like list_update_sets (generic listing) and list_changesets (code commits). However, it doesn't explicitly name an alternative sibling for differentiation, only implicitly distinguishing via the artifact-by-name 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use it ('before you touch it', when checking in-flight or captured promotion changes). It effectively conveys the timing and scenario of use. However, it doesn't explicitly state when NOT to use it or name specific alternative tools, so it misses the 'when-not' exclusion that would push it to 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 description correctly implies no side effects. It adds the important requirement FLUENT_ENABLED=true and the exact command executed, exceeding what annotations provide. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no waste, front-loaded with the action and command. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 is fairly complete. It covers purpose, action, and a requirement. Could add what happens on validation failure, but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter. The description adds no extra meaning beyond the schema's explanation of the 'directory' parameter, 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.
Purpose4/5Does 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 and specifies the command run. It distinguishes from siblings like fluent_build and fluent_init by focusing on validation, but does not explicitly differentiate from other validation tools among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 when to use validate vs other fluent tools or when validation is needed. Only mentions a requirement, but no 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. The description adds minor context by mentioning 'financial and lifecycle data', but does not elaborate on behavior like pagination, permissions, or response structure 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the purpose. No unnecessary words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required param, no output schema, annotations covering behavior), the description adequately conveys what the tool returns. Could mention potential errors or required roles, but the current level is sufficient for common use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the lone parameter 'sys_id' with a description. The description does not add extra meaning or format details. With 100% 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get'), the resource ('IT asset'), and specifies the scope ('full details including financial and lifecycle data'). This distinguishes it from sibling tools like 'list_assets' (which returns a list) and 'get_asset_contracts' (specific contract info).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives (e.g., 'list_assets', 'get_asset_contracts'). There is no mention of prerequisites, limitations, 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true, and the description adds only that it includes variables, which is expected for a detail getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence with no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 good annotations, the description adequately covers the purpose and scope, though it could mention the return payload structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the parameter description 'Catalog item sys_id or name'. The description does not add additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Get) and resource (full details of a catalog item including variables), distinguishing it from siblings like list_catalog_items or update_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 Guidelines2/5Does 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 list_catalog_items for listing or get_record for generic details.
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 and openWorldHint, so the description's contribution is limited. It adds the fields returned but does not disclose additional behavioral traits such as authentication requirements, rate limits, or error conditions. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence that is front-loaded with the core purpose and includes a parenthetical list of key fields. No unnecessary words, efficiently conveying the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter get tool, the description is adequate. It covers the purpose and output, and the schema covers input. However, it could be more complete by clarifying that it returns a single contact or how conflicts are resolved for ambiguous inputs, but given the low complexity, it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of the parameter. The tool description adds value by listing the output fields, which helps the agent understand what the parameter is used for, but the schema already handles the parameter semantics well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves details of a customer contact, listing specific fields like name, account, phone, and email. It distinguishes itself from list_csm_contacts by focusing on a single contact's details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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_csm_contacts or other get_ tools. The description lacks context on when not to use it or what distinguishes it, forcing the agent to infer from naming conventions.
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 adds context about filtering to failed flow executions. However, it does not disclose pagination, limits, or other behavioral details 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core purpose. It is efficient and avoids unnecessary words, though it could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description could be more complete by hinting at the structure of the error logs. However, the context signals (low complexity, annotations present) make it minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well-documented. The description adds no additional semantic information about the parameters beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('detailed error logs'), and the scope ('for failed flow executions'), distinguishing it from siblings like get_flow_execution which retrieve execution details rather than 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing error logs for failed flows, but provides no explicit guidance on when not to use it or alternatives among sibling tools such as get_sys_log or get_email_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?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description does not add additional behavioral context such as authentication needs, rate limits, or return format, but it aligns with the safe read nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 10 words, making it very concise. However, it could include a hint about the return format or list structure, which would improve completeness without much bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 ideally hint at what is returned. It only mentions 'get events' but not that it returns a list or pagination details. The limit parameter suggests pagination, but this is not explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already described. The description adds only marginal value by repeating the event types; it doesn't provide deeper semantic context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves HR lifecycle events for an employee, with specific examples (promotions, transfers, leaves). This distinguishes it from sibling tools like get_hr_case and get_hr_profile, which deal with different HR data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for lifecycle events but does not explicitly state when to use this tool versus alternatives. No when-not or exclusion criteria 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. Description adds context about data retrieved but no additional behavioral details (e.g., permissions, pagination, or external dependencies). 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, direct and efficient. No redundant information. Ideal length for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a straightforward read operation with clear annotations and schema, the description covers essential context. Missing details on output format or permission requirements but acceptable given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description for user_identifier covers accepted formats (username, email, sys_id). Description does not add extra meaning beyond schema, but schema coverage is 100%, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves HR profile for a user and specifies included data (employment details, department, manager). Distinguishes from siblings like get_hr_case by focusing on profile versus other HR entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 get_hr_case, get_hr_service, or update_hr_profile. Agent would need to infer usage from purpose 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, so the description's claim 'Get details' is consistent. However, the description adds no behavioral context beyond what annotations provide, such as side effects or authorization needs. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 9 words, efficiently conveying the core purpose. No extraneous information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 is largely sufficient. It clearly states what the tool does. However, it could briefly mention that it returns the full configuration record. Given the minimal complexity, a score of 4 is justified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the only parameter 'sys_id' is described. The description does not add any additional meaning beyond the schema; it does not explain the format or origin of the sys_id. The baseline of 3 applies as 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get details') and resource ('mobile app configuration'), clearly indicating a retrieval operation. It distinguishes itself from sibling tools like 'list_mobile_app_configs' (which lists all) and 'create_mobile_app_config' (which creates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks any guidance on when to use this tool versus alternatives. It does not mention that 'list_mobile_app_configs' is for listing all configurations or that this tool requires a specific sys_id. No exclusions or context 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 annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't contradict them. The description adds the useful clarification that the mapping is configured in Copilot Studio on the Microsoft side, which helps set expectations about what the tool can and cannot do. With good 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the primary purpose and followed by an important caveat. The second sentence about Copilot Studio configuration earns its place by setting expectations and preventing the agent from incorrectly expecting mapping configuration to be exposed via the API. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read-only listing tool with readOnlyHint and openWorldHint annotations and 100% schema coverage, the description is largely complete. It covers purpose, scope, and an important architectural caveat. Given the tool's simplicity, there's little else it could meaningfully add. The output schema absence is acceptable for a straightforward list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and there's only one optional parameter (limit). A single optional limit parameter with clear default documentation is straightforward; the description doesn't repeat what's in the schema. Description appropriately doesn't waste space explaining parameters that are already fully documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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, with a specific verb (List) and resource. It distinguishes from the sibling get_virtual_agent_topics by scoping to MS Copilot specifically, though it doesn't explicitly name the sibling. The second sentence usefully clarifies that topic mapping is configured on the Microsoft side.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context that this is for Microsoft Copilot integrations and implies it's a read-only listing tool. However, it doesn't explicitly state when to prefer this over get_virtual_agent_topics or other listing tools, nor does it give when-not-to-use guidance. The note about Copilot mapping being external is helpful context but not usage guidance per se.
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, indicating safe read. Description adds no extra behavioral context such as pagination, sorting, or handling of empty results. No contradiction, but little 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose, zero wasted words. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one optional parameter and no output schema, the description covers core purpose adequately. Could mention return format, but not necessary given annotations. Slightly incomplete but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with description for 'state' parameter. Description does not mention the parameter, so it adds no meaning beyond what the schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'List' and resource 'approvals' with clear scoping 'pending for the currently configured user'. This distinguishes it from sibling 'list_approvals' which likely lists all approvals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage when user wants own pending approvals, but does not explicitly state when not to use or mention alternatives like 'list_approvals'. Context is clear but guidance is minimal.
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 that the tool returns 'full details including template and conditions,' providing useful context but not exhaustive 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words, clearly stating the action and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 conveys the purpose and return value (full details including template and conditions). It is complete enough for an agent to understand its use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents the single parameter. The tool description does not add additional parameter-level information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves full details of an email notification definition, specifying it includes template and conditions. This distinguishes it from sibling tools like list_notifications (list) and update_notification (modify).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives, such as using list_notifications for summaries or when full details are not 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 readOnlyHint=true and openWorldHint=true, so the agent knows it's safe and non-destructive. The description adds 'breach status' but doesn't explain output format or limitations beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, immediately conveys the tool's purpose. Front-loaded with verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no output schema, read-only annotations), the description is fairly complete. Only missing is usage guidance, but overall adequate for a straightforward retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a clear description for the sole parameter 'task_sys_id'. The tool description adds no further semantic value about the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action 'Get', the resource 'SLA breach status', and specifies scope 'for a specific task or incident'. It is concise and differentiates from siblings like 'get_csm_case_sla' by being more general.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 'list_active_slas' or 'get_csm_case_sla'. No context about prerequisites or when not to use.
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 description adds value by specifying the details included (inputs, outputs, actions). However, it does not disclose other behavioral aspects like authentication assumptions or response size. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, ten words, front-loaded with the key purpose. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description adequately covers what the tool returns ('full details including inputs, outputs, actions'). It is complete for a read operation on a specific subflow, though it could mention that it returns a single object.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter 'name_or_sysid' is fully described in the schema (100% coverage). The description does not add extra meaning beyond 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get full details') and resource ('subflow'), specifying what is included (inputs, outputs, actions). This distinguishes it from siblings like 'list_subflows' (which lists) and 'get_flow' (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 Guidelines2/5Does 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 'list_subflows' or 'get_record'. The agent must infer context from the name alone, which is insufficient for optimal 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, so the description's claim of 'Get' is consistent. However, the description adds no additional behavioral context beyond what annotations provide, such as error handling 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the purpose. No wasted words, appropriate for the simplicity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 is sufficiently complete. It mentions both value and metadata, though some agents might benefit from knowing the exact return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a clear description for the 'name' parameter. The description's 'by name' is redundant, adding no new meaning beyond the schema. Baseline 3 applies due to high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a ServiceNow system property value and metadata by name. The verb 'Get' and resource are specific, and it distinguishes from sibling tools like 'set_system_property' or 'list_system_properties' that perform 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 Guidelines2/5Does 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 'search_system_properties' or 'list_system_properties'. The description only states what it does, without context for appropriate 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?
Annotations provide readOnlyHint and openWorldHint, so the agent knows this is a read operation with dynamic schema. The description adds no further behavioral traits beyond what is implied by the name and annotations. It does not contradict, so baseline 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that conveys the purpose with no unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema), the description is largely complete. It explains what the tool returns (structure and field information), though it could be slightly more specific about the format. However, 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'table' is fully described in the schema with 'Table name to inspect'. The description adds no additional meaning beyond the schema, so it meets 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets structure and field information for a ServiceNow table, using a specific verb and resource. The tool name is also distinct from sibling tools, which focus on records or other 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/5Does 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 prerequisites, shared dependencies, 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds no additional behavioral details beyond listing. It's adequate but does not enrich the agent's understanding of side effects or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that immediately states the tool's purpose. No unnecessary words, 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with optional filters and no output schema, the description is fairly complete. It could mention the return type (list of suites) but overall it's sufficient given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema descriptions cover 100% of parameters, so the description doesn't need to add more. It provides no extra meaning beyond what the schema already offers, baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists ATF test suites, distinguishing it from sibling tools like get_atf_suite (single) or list_atf_tests (different entity). The verb 'list' and resource 'ATF test suites' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 like get_atf_suite or list_atf_tests. No context on prerequisites or exclusions. The description lacks 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 and openWorldHint, so the description does not need to restate those. The description adds no additional behavioral context beyond what is implied by the tool type and annotations. It is adequate 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that communicates the core purpose without any extraneous words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (1 optional parameter, no output schema), the description adequately covers the core functionality. It mentions both listing and run status. However, it could be more complete by hinting at output format, but it's not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with a description. The tool description does not add any further meaning beyond the schema's existing description. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'discovery schedules', and adds the detail 'and their run status', which distinguishes it from generic list 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/5Does 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 vs alternatives. There is no mention of when to choose it over other list tools or any 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 already declare readOnlyHint=true and openWorldHint=true. The description adds that it lists 'all' knowledge bases, which provides scope but not additional behavioral details like pagination, ordering, or side effects. Value added 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose. 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/5Given 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 that cover safety and openness, the description is fairly complete. It doesn't explain what a knowledge base is, but the purpose is clear given domain context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the 'limit' parameter already described as 'Max results (default: 20)'. The description does not add any extra meaning 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/5Does 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 'knowledge bases', with scope 'all...available in the instance'. This distinguishes it from sibling list tools like list_ai_agents or list_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/5Does 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, prerequisites, or alternatives. The description does not mention any conditions or compare with other list tools, leaving the agent 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.
- 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 marginal context about segmenting data but does not provide additional behavioral traits 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant information. Every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (list with two optional parameters) and the presence of annotations, the description is adequate. However, it does not mention that the list may be paginated or that openWorldHint implies incompleteness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have descriptions in the schema. The tool description does not add additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'PA breakdowns (dimensions)', and the purpose 'available for segmenting indicator data'. It distinguishes from sibling tools like list_pa_indicators and list_pa_dashboards.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 many sibling tools, the lack of usage context is a 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, covering safety and dynamic data. The description adds that it lists 'data collection jobs and their schedules', which is a basic behavioral claim but does not add meaningful transparency 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It is concise but could benefit from slightly more detail (e.g., default filtering behavior) without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and three optional parameters, the description is minimal. It does not explain return format, default values for parameters (e.g., active=true), or behavior when no jobs match. Adequate for a simple list tool but lacks completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully describes the three parameters (limit, query, active). The description does not add any additional meaning or examples for these parameters, thus not exceeding the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'List', the resource 'Performance Analytics data collection jobs', and includes 'their schedules', distinguishing it from related tools like 'get_pa_job' which retrieves a single job. 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 Guidelines3/5Does 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 or any prerequisites. While the purpose is clear, there is no explicit 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description confirms the read-only nature of the tool ('Show') which aligns with the readOnlyHint annotation. However, it adds no behavioral details beyond the annotations, such as whether relationships are direct or transitive, or any potential limitations. With annotations already indicating safety, the description's contribution 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 8 words, extremely concise and front-loaded with the key action and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 adequately covers what the tool does and the required input. It could be slightly more specific about the nature of the relationships (e.g., direct only or all levels), but it remains sufficient for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'ci_sys_id' is fully described in the schema (100% coverage) as 'System ID of the CI'. The description mentions 'for a CI', reinforcing the parameter's purpose without adding new semantic details. Baseline score of 3 is appropriate as the description complements but does not extend the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Show parent and child relationships for a CI'. The verb 'show' indicates a read operation, and 'parent and child relationships' specifies exactly what is retrieved, distinguishing it from other list tools like list_incidents or list_users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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 like create_ci_relationship or other list tools. Usage is implied based on the need to retrieve relationships, but no when-not-to-use 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 indicate readOnlyHint=true and openWorldHint=true. The description adds 'run schedules' as a behavioral detail but does not disclose additional traits like pagination, default behavior, or response format. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded. There is no superfluous content; every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple listing operation with high schema coverage and no output schema, the description is nearly complete. It lacks mention of default limit or explicit statement that it lists all scheduled jobs, but openWorldHint covers scope. Overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described in the schema. The description does not add meaning beyond the schema, but the mention of 'run schedules' indirectly hints at the scope. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List scheduled jobs and their run schedules' clearly states the action (list) and resource (scheduled jobs) and includes the relevant detail of run schedules. It distinguishes from sibling tools like list_job_run_history (run history) and get_scheduled_job (single job).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, no filtering context, and no mention of prerequisites or exclusions. It simply says what it does without usage 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 and openWorldHint, so the description's addition of a prerequisite is useful context. No behavioral traits beyond annotations are disclosed, but 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that concisely states purpose and a key requirement. No unnecessary words, but it could be slightly more informative about return values.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations and schema, the description is minimally adequate. It covers the core purpose and prerequisite, but lacks details like pagination or return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description does not add extra meaning to the parameters beyond what the schema 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (script_includes), with a parenthetical prerequisite. It distinguishes from sibling tools like create_script_include or 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a prerequisite (SCRIPTING_ENABLED=true), which provides some guidance on when to use the tool. However, it does not explicitly state when to avoid it or mention 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, so the description's 'list' aligns. However, description adds little beyond that, such as pagination behavior or performance traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that is front-loaded and contains no extraneous information. It directly communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with optional parameters and no output schema, the description is adequate. It could mention that it lists all licenses or that query is encoded, but it covers the basics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 does not add any extra meaning beyond what is already in the schema, baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and specifies the resource 'software license records' and what is included 'compliance status'. It clearly distinguishes from other list tools by focusing on software licenses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 get_license_compliance or get_license_optimization. No mention of prerequisites or context for use.
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 'List' matches. However, the description adds no additional behavioral context (e.g., pagination, default limit). With annotations present, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that is front-loaded with the core purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with optional parameters and safety annotations, the description covers the essential purpose. It could mention the output format, but that is not critical given the tool's straightforward nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters (limit, scope) with descriptions. The description adds no extra meaning beyond what the schema provides. 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'UI Builder components', and the scope 'in the instance'. It effectively distinguishes this tool from siblings like 'list_uib_pages' or 'list_uib_data_brokers'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 like 'list_uib_pages' or 'list_uib_data_brokers'. There is no mention of prerequisites or filtering context beyond the scope parameter.
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 the qualifier 'configurable' but no additional behavioral context beyond what annotations convey. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundant words. Front-loaded with verb and resource. Appropriate length for a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a basic list tool with two optional parameters, but lacks explanation of 'configurable agent workspaces' and return format. Falls short of fully setting context for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (active parameter has description, limit does not). The description adds no parameter-level details; it does not compensate for the undocumented limit parameter or clarify its usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'configurable agent workspaces,' clearly distinguishing it from sibling list tools targeting other entities. It covers the tool's core function 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this vs. alternatives like list_ai_agents or list_workspace (if it existed). Usage is implied by the resource name, but no exclusions or context 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 adds that it performs anomaly detection, which is consistent. However, the description does not elaborate on behavioral traits beyond the annotations, such as output format 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence with no redundant words. It is front-loaded with the core purpose and 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.
Completeness2/5Given 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 explain what the tool returns (e.g., anomalies with scores, timestamps). Additionally, there is no guidance on parameter interactions or typical usage context, leaving the agent potentially underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions, so the schema already explains all parameters (days, field, table, threshold). The description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 target ('operational metrics' like alert volume, incident trends). This differentiates it from sibling tools such as ml_forecast_incidents or ml_predict_change_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for detecting anomalies in operational metrics but provides no explicit guidance on when to use versus alternatives, nor when not to use it. It lacks contextual cues for agent decision-making.
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, making the read-only nature clear. The description adds no additional behavioral context (e.g., data freshness, pagination, auth requirements) beyond what annotations provide, so it meets the baseline but adds no 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the key action and object. Every word is necessary 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity of the tool (2 parameters, no output schema), the description adequately conveys the purpose and expected output (history and trends). However, it could briefly mention the output format or structure for fuller completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, describing both parameters ('days' and 'model_sys_id'). The description does not add any extra meaning or usage context for these parameters beyond the schema, so it achieves the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resources 'training run history and accuracy trends' for 'an ML solution over time', which is specific and distinguishes it from sibling tools like ml_evaluate_model or ml_forecast_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/5Does 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 ml_evaluate_model or other ML tools. It does not mention prerequisites, 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 indicate readOnlyHint=false and openWorldHint=true, but the description says 'Preview', which is read-like. The description does not clarify potential side effects or pagination 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what the tool returns (e.g., list of changes with details). It does not, leaving the agent uncertain about the output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are described in the schema. The description 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Preview') and the resource ('all changes contained in an Update Set'), which is specific and distinguishes it from sibling tools like 'get_update_set' or 'list_update_sets'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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. The name implies it's for previewing before committing, but this is not 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 provide idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds [Write] which confirms write semantics but does not provide further behavioral context like scope or impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence plus a tag, no fluff. Every word is useful and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 informative annotations, the description is adequate. However, it could slightly improve by noting the idempotent nature or linking to related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all 4 parameters with descriptions. The description does not add extra meaning beyond what the schema provides, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Create or update' and resource 'system property' are stated. The [Write] tag reinforces the action. This distinguishes it from sibling tools like update_record or delete_system_property.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. For example, it doesn't clarify that this is specific to system properties and not general records. No context on prerequisites or when to avoid.
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-destructive (destructiveHint=false), and idempotent (idempotentHint=true). The description adds a requirement (WRITE_ENABLED=true) but does not disclose further behavioral traits like whether the update is partial or full, or side effects on related 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys purpose and a key requirement. It is front-loaded with the action and resource, with no superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description should explain what the tool returns (e.g., the updated article or a success indicator), but it does not. Additionally, with many similar siblings, it lacks guidance on when to use this tool over others. The description is incomplete for a tool with two required parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and both parameters have descriptions. The description itself adds no additional meaning beyond the schema. The example in the schema (e.g., {'text': '...'}) is helpful, but the description does not compensate for any lack in schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'knowledge article', distinguishing it from many sibling tools that operate on other entities. The requirement 'requires WRITE_ENABLED=true' 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a precondition (WRITE_ENABLED=true), providing some guidance on when the tool can be used. However, it does not explain when to choose this tool over alternatives like update_record or update_any_resource, nor does it give context on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide key traits (idempotent, non-destructive, open world). The description adds valuable behavioral context: a permission requirement (WRITE_ENABLED=true) and the dry_run feature, which previews changes without writing. This exceeds what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no extraneous content. The first sentence states the core purpose and a key requirement; the second introduces the dry_run feature. Information is front-loaded, making it efficient for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers purpose and a key option, it lacks output format details (no output schema) and usage guidance among many sibling update tools. For a generic mutation tool, this is adequate but incomplete for an AI agent to fully understand behavior and results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description adds the authorization condition (WRITE_ENABLED=true) not present in the schema, enhancing parameter understanding. It does not elaborate on the fields object structure beyond 'key-value pairs', but the added context justifies a higher score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing record in any ServiceNow table, specifying the verb and resource. However, it does not explicitly differentiate from sibling update tools (e.g., update_incident), which diminishes clarity for an AI agent choosing between generic and specialized 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks guidance on when to use this generic tool versus dedicated update tools like update_incident. It only mentions a prerequisite (WRITE_ENABLED=true) and the dry_run option, but no context on alternatives or 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 indicate idempotency and non-destructiveness. The description adds the requirement 'WRITE_ENABLED=true' which provides useful context beyond annotations, but does not disclose side effects or specifics of the update 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and efficient, containing only one sentence. It conveys the core purpose and a requirement without wasted words, though it could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 well-documented parameters and annotations, the description is adequate. It mentions the key requirement but lacks details about return values or potential side effects, which are not covered by output schema (absent).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers both parameters with descriptions, achieving 100% coverage. The description adds no additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'scheduled job', distinguishing it from sibling tools like create_scheduled_job or get_scheduled_job. The requirement 'WRITE_ENABLED=true' 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating an existing scheduled job but does not explicitly state when to use this tool versus alternatives like create_scheduled_job for new jobs. The requirement is noted but no exclusion 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 indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds a [Write] tag and 'Create or update', but no additional behavioral details like error handling 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence plus a tag, front-loaded with action, zero waste. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core function adequately for a low-complexity tool with one parameter and annotations. However, it lacks guidance on limits, returns, or comparison to set_system_property, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the single parameter 'properties'. The description adds context of 'multiple' and 'single operation' but does not clarify upsert behavior or constraints on array size.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create or update multiple system properties in a single operation.' It specifies the verb (create/update), resource (system properties), and scope (multiple, single operation), distinguishing it from singleton tools like set_system_property.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for multiple properties at once but does not explicitly state when to use versus alternatives like set_system_property. No guidance on batch limits or preconditions.
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. The description adds the WRITE_ENABLED requirement, which is useful but does not significantly expand beyond annotations. No mention of side effects or confirmation 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It includes the key action and a conditional requirement, earning its place efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the straightforward tool (close case with notes) and presence of annotations, the description is adequate but lacks details on outcome, error handling, or state changes. Could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all 3 parameters. The description does not add additional meaning beyond 'resolution details', so it provides no added value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Close a CSM case with resolution details'. It includes a prerequisite (WRITE_ENABLED=true) and distinguishes from sibling tools like close_hr_case or close_incident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context (requires WRITE_ENABLED=true) but does not explicitly state when to use this tool versus alternatives or when not to use it. No guidance on prerequisites beyond the flag.
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?
Description describes write operations (merge, retire, remove) but annotations declare readOnlyHint=true, creating a direct contradiction. This severely undermines 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key action and resource, no filler. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core functionality, permissions, and mode. Missing output schema explanation and lacks explicit connection to find tools. Adequate but not exceptional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). Description adds meaning by grouping actions with CI types and clarifying dry_run as preview mode, providing context beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool acts on duplicate, stale, or orphan CIs with specific actions (merge, retire, remove). It distinguishes from sibling cmdb_find_* tools which are for discovery only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description indicates when to use (reconciliation), mentions required permission (CMDB_WRITE_ENABLED), and dry_run mode for safe preview. Lacks explicit alternatives or 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 indicate non-readonly and non-destructive behavior, and the description adds the important constraint that WRITE_ENABLED must be true. This goes beyond what annotations provide, though it could detail effects like whether the task becomes read-only or triggers workflows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is 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 requirement with no wasted words. It earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool without output schema, the description provides the essential action and a prerequisite. However, it omits information about return values, side effects (e.g., state changes), and error conditions, leaving the agent somewhat underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters ('sys_id' and 'close_notes'). The description adds no additional 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('mark as complete') and the resource ('task'), with a specific prerequisite highlighted. However, it does not differentiate from sibling tools like 'close_incident' or 'close_change_request' which may have more specific use 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a critical prerequisite ('requires WRITE_ENABLED=true'), providing some context for when the tool is usable. However, it lacks guidance on when to use this generic 'complete_task' versus more specific completion tools for different task types.
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 non-read-only, idempotent, and non-destructive. The description adds 'Add or update' and '[Write]', which are consistent with annotations but provide no additional behavioral context beyond what is already known.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with an additional tag. It is concise and front-loaded, but the bracketed '[Write]' is redundant given the annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich annotations and complete schema, the description adequately covers the tool's purpose. No output schema exists, but the behavior is straightforward. Some users might benefit from an example or note on idempotency, but current text is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage of parameter descriptions. The description adds no further semantic detail about parameters such as default behavior, format constraints, or interdependencies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (add or update), the resource (list view), and the context (agent workspace). It effectively distinguishes from sibling tools like create_workspace or update_workspace, which deal with workspaces themselves rather than list views.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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, or any prerequisites. The name and context imply it is for list view configuration, but this is not directly 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 indicate write operation (readOnlyHint=false) with potential side effects (openWorldHint=true). The description adds the prerequisite and ES2021 support, which provides some behavioral context beyond annotations but does not fully disclose side effects or result 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of two sentences that deliver key information without unnecessary words. It effectively front-loads the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters and no output schema, the description is relatively sparse. It covers the main action and a prerequisite but does not explain return values or confirm what happens on success. Schema fills some gaps but completeness could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters have descriptions. The description does not add additional meaning beyond the schema, except for the ES2021 note which is already in the script parameter description. 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and resource 'business rule', and adds a prerequisite (SCRIPTING_ENABLED=true). It also provides a capability note (ES2021 support). It distinguishes itself from siblings like get_business_rule and update_business_rule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (SCRIPTING_ENABLED=true) which indicates when to use, but does not explicitly state when not to use or provide alternatives (e.g., update_business_rule for modifications). Guidance is minimal.
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 (write operation) and destructiveHint=false. The description adds no behavioral context beyond '[Write] Create', which aligns with annotations. No contradiction, but no enrichment either.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence with a [Write] prefix, conveying the essential purpose without any fluff. Every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters and no output schema, the description is minimal but sufficient for basic understanding. However, it lacks usage guidelines and behavioral details that would help an agent use it correctly, though annotations partially compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description does not reference any parameters, so it adds no meaning beyond the input schema. 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description includes a [Write] prefix and explicitly states 'Create a UI policy for a catalog item form', using a specific verb and resource. It distinguishes from sibling create_ui_policy (generic) by specifying 'catalog item form'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for catalog item forms but does not explicitly state when to use this tool versus alternatives like create_ui_policy (general) or create_ui_action. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions a prerequisite (SCRIPTING_ENABLED=true) but does not disclose other behavioral traits such as what happens on creation (e.g., immediate activation, side effects, or error cases). Annotations already indicate it is not destructive, so the description adds minimal value beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence containing only essential information. It is front-loaded with the action and resource, followed by a key requirement in parentheses, with no superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, no output schema, and annotations, the description is minimal but covers the core purpose. It lacks details about return values, error handling, or relationships with sibling tools like update_client_script. For a creation tool, the description is acceptable but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for all 7 parameters, so the description adds no extra meaning. The schema already captures the script types, required fields, and defaults. The description's mention of script types is redundant with the schema's enum-like description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'client script', specifies the script types (onLoad, onChange, onSubmit, onCellEdit), and includes a prerequisite. It distinguishes this tool from other 'create_*' siblings by being specific to client scripts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a required condition (SCRIPTING_ENABLED=true) which helps in deciding when to use the tool. However, it does not explicitly state when to avoid this tool or recommend alternatives (e.g., update_client_script 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 readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds the required permissions, which is useful, but does not disclose any additional 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/5Is 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 key constraints. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a creation tool with a clear schema and annotations, but it lacks information about return values or outcomes. Given no output schema, some guidance on response would be helpful. Overall, it meets minimal completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; it only mentions 'ordered steps' which is already in the schema. No additional parameter context is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 adds key details like 'ordered steps that chain tool calls' and required permissions (NOW_ASSIST_ENABLED + WRITE_ENABLED). This distinguishes it from similar 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite (NOW_ASSIST_ENABLED + WRITE_ENABLED) but does not specify when to use this tool versus alternatives like 'create_agentic_workflow'. No guidance on when not to use it 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 indicate a write operation (readOnlyHint=false). The description adds the WRITE_ENABLED permission requirement, which is useful. However, no side effects, return format, or error conditions are disclosed, so the description adds limited 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, no redundancy, and essential content only. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, no output schema, and moderate complexity, the description provides minimal context. It does not explain the concept of a saved report, how it integrates with other tools, or what the agent should expect after creation. However, the detailed schema partially compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 8 parameters. The description does not add any additional meaning or usage hints for specific parameters, hence baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and resource 'a new saved report on any table', with a specific prerequisite. It distinguishes from sibling 'create_scheduled_report' and other 'create_*' tools by focusing on saved reports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (WRITE_ENABLED=true) but provides no guidance on when to use this tool versus alternatives like 'update_report', 'get_report', or 'list_reports'. Usage 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (mutation) and openWorldHint=true (side effects). The description adds a critical behavioral constraint: the tool requires SCRIPTING_ENABLED=true to function. This is valuable transparency beyond the annotations, though it does not disclose rate limits, authentication needs, or detailed 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that communicates the tool's purpose and a key requirement. Every word is necessary, and it is front-loaded. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters (2 required), no output schema, and the context of a complex platform (ServiceNow), the description is too brief. It does not explain what 'control field behavior dynamically' entails, nor does it provide examples or mention potential side effects. The description is minimally adequate but lacks depth for a tool that modifies system behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and each parameter has a description in the schema. The tool's description does not add any additional semantics or context for the parameters 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create'), the resource ('UI Policy'), and its purpose ('to control field behavior dynamically'). It also includes a key prerequisite ('requires SCRIPTING_ENABLED=true'). This distinguishes the tool from other 'create_*' tools in the sibling list by specifying the exact artifact being created.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (SCRIPTING_ENABLED) but provides no guidance on when to use this tool versus alternatives like 'create_ui_action' or 'create_catalog_ui_policy'. There is no explicit 'when to use' or 'when not to use' context, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it's a mutable, non-idempotent, non-destructive operation. The description adds the behavioral context of step-by-step execution with result passing through context, and the dry_run capability. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the core purpose, prerequisite, and a key feature. It is concise and front-loaded, though it could be slightly more structured with bullet points for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a complex nested input schema but no output schema. The description explains the execution flow but does not mention return values, error handling, or limitations. Given the complexity and lack of output schema, the description is incomplete for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the three parameters. The description only hints at context and dry_run implicitly without adding new semantic meaning beyond what the schema provides. Baseline score 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Execute' and the resource 'playbook', specifying the step-by-step execution with context passing. It distinguishes from siblings like create_playbook or list_playbooks by focusing on execution. The mention of 'requires NOW_ASSIST_ENABLED' and 'Supports dry_run' 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a prerequisite (NOW_ASSIST_ENABLED) and mentions dry_run as a feature, but it does not explicitly state when to use this tool versus alternatives like trigger_agentic_playbook or create_playbook. No explicit when-not-to-use or exclusions 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 provide readOnlyHint=true and openWorldHint=true, indicating safe read operation and potential dynamic state. The description adds the 'environment snapshots' context but does not disclose additional behavioral traits like what happens with empty query, output format, or rate limits. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that captures the core action and use case without 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.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and use case but lacks details on output format, default behavior when query is omitted, and whether all properties are exported if no query is provided. Given no output schema and optional parameters, more completeness would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters (query, category) described. The description mentions 'matching a query' which aligns with the query parameter, but does not add semantic value beyond the schema's descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports system properties matching a query to a JSON object, with a specific use case (environment snapshots). This distinguishes it from sibling tools like list_system_properties which list properties, and get_system_property which retrieves a single property.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a use case (environment snapshots) but does not explicitly guide when to use this tool over alternatives like list_system_properties, get_system_property, or search_system_properties. It lacks when-not-to-use and exclusion 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 declare readOnlyHint=true and openWorldHint=true, establishing safety. The description adds that the tool returns records or aggregate results, which is consistent but does not disclose additional behavioral traits (e.g., default limit, performance implications). 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences plus an example, front-loaded with the core identity. No redundant information; every sentence contributes to understanding purpose, capabilities, and usage pattern. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While description covers basic capabilities and provides an example, it lacks context on default behaviors (e.g., limit default 20, max 200), pagination, or performance considerations. Given the tool's complexity (10 parameters) and the presence of many sibling query tools, more contextual guidance would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing detailed parameter descriptions. The tool description adds value with a concise example demonstrating how parameters combine (e.g., where, select, limit) and lists supported aggregate operations, enhancing semantic understanding beyond individual parameter docs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's purpose as a 'GlideQuery-style fluent query builder' with specific supported operations (select, where, aggregate, orderBy, limit, groupBy) and return types (records or aggregate results). This distinguishes it from sibling query tools like query_records and run_aggregate_query by emphasizing its fluent style and comprehensive capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. The description implies a comprehensive query capability but does not contrast with simpler query tools (e.g., query_records) or aggregate-only tools (e.g., run_aggregate_query). Lacks when-to-use or when-not-to-use 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 (safe read) and openWorldHint=true (unexpected fields possible). The description adds specific content details ('body and headers'), but does not disclose behavior for missing sys_id or response size. Overall, it provides useful 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence with no wasted words. It is front-loaded with the key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could be more helpful by indicating the return format or fields. It mentions 'full details' but is vague. For a simple get operation, 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with sys_id described as 'Email log sys_id'. The description does not add additional meaning beyond the schema; it implies the parameter identifies the log entry but provides no extra syntax or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('email log entry'), and specifies what is included ('body and headers'). This distinguishes it from sibling tools like 'list_email_logs' which lists entries 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 Guidelines2/5Does 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_email_logs', 'get_record', or 'get_sys_log'. There is no mention of prerequisites or conditions for use.
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 no extra behavioral details beyond stating it's a read operation. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, no unnecessary words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple get operation with read-only annotations and no output schema, but could be more specific about what 'details' includes in the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter well-described in the schema. The description adds no additional meaning beyond what the schema provides for 'execution_sysid'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get the status and details of a specific flow execution' clearly states the action (get) and resource (flow execution), distinguishing it from listing tools like 'list_flow_executions' that require a sys_id parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like 'list_flow_executions'. Usage is implied by requiring a specific execution_sysid, but no when-not or alternative comparisons 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 readOnlyHint=true and openWorldHint=true, so the tool is known to be safe and non-destructive. The description adds no behavioral context beyond what the schema and annotations provide, such as performance implications or return 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys the core purpose without extraneous information. Every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description sufficiently explains what the tool does, it lacks details on the return value (e.g., it returns an integer count). Given the simplicity and good annotations, a score of 3 is fair.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions for 'table' and 'query'. The description's mention of 'optional filters' adds no new meaning beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get), resource (total record count for a ServiceNow table), and scope (with optional filters). It is specific and easily distinguishes the tool from siblings like compare_record_counts or run_aggregate_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (to get a record count, optionally filtered) but does not explicitly state when not to use it or provide alternatives. No contrast with sibling tools 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 readOnlyHint=true and openWorldHint=true. Description 'Look up user details' is consistent but adds no extra behavioral context beyond what annotations provide, such as permissions or return 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, directly front-loaded with the core purpose. No redundant words. Every part of the description is useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with no output schema, the description lacks detail about what 'user details' include. No mention of return structure or potential error conditions, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes user_identifier as 'Email address or username'. Description restates this but adds no additional semantics (e.g., format, case sensitivity). Baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Look up user details by email or username', specifying the verb (look up), resource (user details), and method (email or username). This distinguishes it from sibling tools like list_users which returns multiple users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage for a single user by identifier, but does not explicitly state when to use this vs. alternatives like list_users or get_group. No exclusion criteria 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, covering the behavioral safety profile. The description adds that the tool returns CVSS score and affected CIs, which is useful context but does not disclose any additional behavioral traits beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with 13 words, efficiently conveying the purpose and key details. No fluff or redundancy; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get operation with one parameter and no output schema, the description is adequate but lacks details on the return format, error handling, or confirmation that it returns a single record. Annotations cover read-only aspects, so it's minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 'number_or_sysid', which is already described as 'Vulnerability number (VIT...) or sys_id'. The description adds no further meaning 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/5Does 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 'vulnerability entry', specifying key details like CVSS score and affected CIs. This distinguishes it from sibling tools like 'list_vulnerabilities' (which lists many) and 'update_vulnerability' (which modifies).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving details of a specific vulnerability but does not explicitly guide the agent on when to use this tool vs alternatives like 'list_vulnerabilities' or 'update_vulnerability'. No exclusion criteria 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 provide readOnlyHint and openWorldHint, so the description's addition of 'who has opted in/out' adds minimal behavioral context. It does not disclose pagination, ordering, or other behavioral traits beyond what annotations 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without wasted words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description could benefit from mentioning return format or default behavior. It covers the basic purpose but misses details like pagination or result fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all parameters (limit, user_sys_id, notification_sys_id). The description adds no extra meaning to these 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/5Does 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 'user subscriptions to notifications', with a parenthetical clarifying it's about opt-in/out status. This distinguishes it from sibling tools like 'list_notifications' which list notification 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing subscriptions but does not explicitly state when to use this tool versus alternatives like 'list_notifications' or 'get_notification'. No exclusions or context 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. The description adds no behavioral details beyond what annotations provide, such as pagination, sorting, or that results are limited. It is adequate 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the essential purpose without any extra 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with comprehensive annotations and schema, the description is sufficient but minimal. It could optionally mention the return structure or the default limit behavior already in schema, but overall 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema fully documents both parameters (widget_sys_id and limit). The description does not add any additional meaning or context about the parameters, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists instances of a specific widget placed on portal pages. The verb 'list' and resource 'instances of a specific widget' are specific, and it distinguishes from sibling tools like list_portal_widgets (lists widgets, not instances) or list_instances (general instances).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when one needs to find where a particular widget is used on portal pages, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., list_portal_widgets) 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.
- 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 reinforces this with '[Write]' but adds no further behavioral context like required permissions or side effects beyond activation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence plus metadata) with no extraneous information. It efficiently conveys the core purpose without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write operation with full schema coverage and safety annotations, the description provides sufficient context. It does not include return value details but no output schema exists to require that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no extra meaning beyond the parameter descriptions. Both parameters are adequately described in the schema, so the description provides no additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('publish/activate') and the resource ('draft flow or subflow'). It distinguishes from sibling tools like publish_changeset and publish_knowledge_article by mentioning the specific 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for publishing drafts but does not explicitly state when to use this tool versus alternatives (e.g., update_flow, create_flow, or other publish tools). No guidance on 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 are present but minimal; the description adds the requirement 'SCRIPTING_ENABLED=true', which is useful. However, it does not disclose other behavioral details like side effects or duplicate 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the action and a key prerequisite with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple registration tool with 3 parameters and no output schema, the description covers the core purpose and a prerequisite but lacks information on return values or operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage with clear parameter names and examples. The description adds no extra meaning 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Register' and the resource 'new custom event in the event registry', distinguishing it from sibling tools like 'fire_event' which trigger events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (SCRIPTING_ENABLED=true) but does not explicitly guide when to use this tool over alternatives like 'fire_event' 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate that the tool is a write operation (readOnlyHint=false) and is idempotent and non-destructive. The description confirms this with 'Update an epic' and adds the WRITE_ENABLED prerequisite, which is consistent. However, it does not elaborate on what happens during the update (e.g., partial vs full replace, error handling, or side effects). Given the annotation coverage, the description adds limited behavioral context beyond confirming the operation type.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that communicates the essential purpose and a key condition without any wasted words. Every element serves a purpose: the action verb, the target resource, and the prerequisite. It is optimally concise for an agent to quickly parse and understand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has a complete parameter schema and annotations covering behavioral aspects, the description is adequate but not comprehensive. It does not explain the return value (there is no output schema) or the effect of the 'fields' parameter (e.g., whether it performs a partial update or full replacement). For a mutating tool without an output schema, a brief note about the update behavior would improve completeness. The current description is minimally sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter schema provides descriptions for both sys_id and fields, achieving 100% coverage. The description does not add any additional meaning beyond what the schema already contains—it merely names the parameters implicitly. Since the schema already does the heavy lifting, a score of 3 is appropriate; the description adds no extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Update an epic', which is a clear verb+resource combination. It also includes the prerequisite condition 'requires WRITE_ENABLED=true', which helps the agent understand the access context and distinguishes this tool from read-only ones like get_epic or list_epics. Among many sibling update tools, the specific resource 'epic' is unambiguously identified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite (WRITE_ENABLED=true) but does not indicate when to avoid using this tool or suggest alternatives. For example, it does not contrast with create_epic for new epics or update_record for non-epic records. The usage guidance is minimal, relying on the agent to infer context from the tool name and sibling 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?
Annotations already indicate write (readOnlyHint=false), idempotency, and non-destructive nature. The description adds the WRITE_ENABLED requirement, but does not elaborate on update behavior (partial vs full replacement) or error handling. Additional context 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence that contains the essential purpose and a key constraint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool without an output schema, the description covers basic purpose and a requirement. However, it lacks information about return values, error conditions, or how updates merge with existing data, leaving some gaps in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters. The description's 'Key-value pairs to update' for fields is redundant with the schema. No new parameter-level meaning is added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a group') and the specific resource. It also mentions a prerequisite (WRITE_ENABLED=true), which helps differentiate from read-only or creation tools like get_group or create_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating a required setting, but it does not explicitly compare with alternative tools (e.g., add_user_to_group) or specify when to avoid using this tool. Guidance is minimal.
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 only the WRITE_ENABLED requirement, which is useful but not enough to elevate the score given the lack of additional 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence of 7 words, with no wasted words. It is maximally concise while still conveying the core purpose and a key requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal. It does not explain whether partial updates are supported, whether the story must exist, or what the response looks like. Given the simple schema and annotations, it is adequate 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds no additional meaning to the parameters beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'agile story', making the tool's purpose unambiguous. It also includes a specific requirement, differentiating it from generic update 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (WRITE_ENABLED=true), which is helpful, but it does not provide guidance on when to use this tool over sibling tools like update_record or update_epic.
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 context beyond annotations: the comment is customer-visible and requires WRITE_ENABLED=true. No contradictions with annotations (readOnlyHint=false). Does not cover edge cases like record existence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, direct, no filler. Front-loaded with the action and key constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with full schema documentation, the description is sufficient. Could mention behavior when WRITE_ENABLED is false or record not found, but not necessary given low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. The description adds value by specifying 'customer-visible' for the comment parameter, but does not add other parameter-specific details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'add a customer-visible comment' and the resource 'any ITSM record'. It distinguishes from sibling like add_work_note by specifying 'customer-visible', but 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a precondition (WRITE_ENABLED=true) but no explicit guidance on when to use vs alternatives like add_work_note or update_record. Usage is implied but not fully contextualized.
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 readOnlyHint=false (write operation) and destructiveHint=true, which are consistent with closing a case. The description adds the precondition 'WRITE_ENABLED=true', but does not disclose other behavioral effects (e.g., status changes, notifications). More context would improve 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no extraneous words. It efficiently conveys the tool's purpose and a key requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple tool with three parameters and no output schema, the description provides the essential context (prerequisite). It could be improved by mentioning expected return values or behavior on failure, but it is sufficiently complete for standard use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have descriptions in the input schema (100% coverage). The description adds minimal extra meaning beyond the schema, mainly confirming that 'close_notes' are resolution notes. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Close'), the resource ('HR case'), and additional context ('with resolution notes, requires WRITE_ENABLED=true'). It effectively distinguishes from sibling tools like update_hr_case or delete_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (WRITE_ENABLED=true) but does not provide explicit guidance on when to use this tool versus alternatives (e.g., when not to use if case already closed). Usage 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 declare readOnlyHint=true and openWorldHint=true. The description adds specific context about the metrics returned but lacks details on behavior beyond that (e.g., response format, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It effectively communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and annotations covering readOnly and openWorld, the description is fairly complete. It states the output clearly, though could elaborate on what 'completeness' means numerically.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is trivially 100%. The description adds meaning by specifying the type of metrics, which is useful context. Baseline 4 for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and a clear resource 'CMDB data quality metrics' with added detail about completeness of server and network CI data. This clearly distinguishes it from sibling tools like cmdb_find_duplicates or cmdb_impact_analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. It does not provide when-not conditions or differentiate usage from similar 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 already indicate write (readOnlyHint=false), non-destructive, non-idempotent. The description adds the 'WRITE_ENABLED=true' requirement, which is additional context. It does not disclose behaviors like validation, error handling, or side effects beyond what the schema (e.g., 'Must already exist' for staging_table) provides. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the action, context, and a key requirement. No extraneous words. It is front-loaded with the core action. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description does not mention what the tool returns (e.g., the sys_id of the created row). This is a gap for a creation tool. It also lacks information about validation, required fields in 'data', or behavior on duplicate rows. Given the complexity of nested objects and the missing output schema, the description is incomplete for confident usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema describes both parameters with clear descriptions. The description echoes the purpose but adds no extra meaning about parameter formats, constraints, or relationships (e.g., what keys are valid in 'data'). Baseline 3 is appropriate as the description does not enhance schema-provided semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Insert a row into an Import Set staging table', which is a specific verb-resource combination. It distinguishes this tool from other create tools like create_record because it targets Import Set staging tables, not regular records. The phrase 'for later transformation' adds context about its purpose in the data flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes the notable requirement 'requires WRITE_ENABLED=true', which is a clear usage condition. However, it does not explicitly mention when to use this tool versus alternatives (e.g., create_record or bulk_create_records), nor does it provide exclusion criteria. The context of 'Import Set staging table' implies a specific use case, but explicit 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 indicate a write operation with no idempotency or destructive hint. The description adds the permission requirement, but does not detail side effects (e.g., triggering flows) 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with parenthetical, no wasted words, front-loaded with the key action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 params, no output schema, annotations present), the description covers the core purpose and key constraint, but could mention the return value or confirmation of firing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema provides 100% coverage of parameter descriptions; the description adds no additional semantic value beyond what the schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (fire), the resource (custom ServiceNow event), and the target (specific record), distinguishing it from sibling tools like register_event or trigger_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the prerequisite WRITE_ENABLED=true, but does not provide guidance on when to use this tool vs alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/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 no further behavioral traits such as authentication needs, rate limits, or return format. It minimally adds that ACLs are included but does not disclose any side effects or 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Front-loaded with the verb and resource, and includes the important addition of 'related ACLs'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 covers the basic purpose. However, it could mention what the return looks like (e.g., definition and ACL list). Still, 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter (sys_id) described as 'System ID of the AI agent'. Description adds no additional meaning or constraints beyond the schema. Baseline 3 is appropriate as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Get' and the resource 'AI agent definition and its related ACLs'. It distinguishes from siblings like 'get_acl' and 'list_ai_agents' by specifying the scope includes both the definition and ACLs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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 'get_acl' or 'list_ai_agents'. The description implies it is for retrieving a specific agent with its ACLs, but does not state exclusions or provide context for choosing among 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 indicate readOnlyHint: true and openWorldHint: true. The description adds that the tool retrieves 'metadata changes between last successful and failed run' and specifies the type of changes (role, field value). This provides behavioral context beyond annotations without 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and specifies the output content. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 adequately conveys what data is returned. However, it does not specify the format or structure of the response, which might be needed for an agent to interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single parameter 'result_sys_id' is sufficiently described in the schema as 'System ID of the failed suite result'. The description does not add additional parameter-level detail, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves ATF Failure Insight data, specifically metadata changes between successful and failed runs, including role changes and field value changes. This is a specific verb+resource+scope that distinguishes it from sibling tools like get_atf_suite or get_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/5Does 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_atf_suite_result or get_atf_failure_insight (it is the tool itself). The description does not mention prerequisites, context of use, 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.
- 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 clarifies that the tool retrieves full details but does not add significant behavioral context beyond what annotations provide. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the essential purpose and identification method without any filler or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, read-only, no output schema), the description is adequate. It specifies the input format but does not detail what 'full details' encompasses; however, the purpose is clear enough for agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single parameter 'number_or_sysid', which already describes it. The description reiterates 'by number (CHG...) or sys_id' but adds no further semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 details of a change request', and specifies the identification method 'by number (CHG...) or sys_id'. It distinguishes from sibling tools like 'list_change_requests' or 'get_incident'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description is minimal and does not explicitly state when to use this tool versus alternatives. While the purpose is clear, no guidance is provided on when not to use it or which other tools might be more appropriate.
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 safe, read-only access. Description adds that the result includes contacts and open cases count, which is useful but does not provide deeper behavioral context like pagination, error conditions, or performance. With annotations covering safety, the description adds moderate 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 12 words that is front-loaded with action and resource. Every word is meaningful, no redundancy. Efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 provides adequate context about what is returned (contacts and open cases count). However, it could be more complete by briefly noting the response structure or example values. Overall, it is sufficient 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter name_or_sysid is described in the schema with its meaning. The description does not add additional semantics (e.g., format, examples, or validation). Since schema coverage is 100%, this meets the baseline but does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves account details with specific contents (contacts and open cases count). The verb 'Get' and resource 'customer account' are specific, and the description distinguishes from sibling list_csm_accounts which returns 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. The description implies retrieval of a single account, but does not contrast with sibling tools like list_csm_accounts or search_csm_accounts. Usage context is implied but not clearly delineated.
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 and openWorldHint. Description adds that details include impact, likelihood, and controls, which is useful but does not disclose additional behavioral traits like data source 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, immediately states purpose and key fields. No redundancy. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no output schema, and annotations covering safety, description lists three return fields (impact, likelihood, controls) which adds context. Lacks details on error handling or missing risks, but sufficient for a simple get operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter 'number_or_sysid' is described in schema (100% coverage). Description adds no new meaning to parameter; it only hints at return fields, which is unrelated. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get details of a GRC risk' with specific verb and resource. It distinguishes from sibling tools like list_grc_risks (list) and create_grc_risk (create) by implying detail retrieval for a single 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implicit: use when needing details of a specific risk. However, no explicit when-not-to-use or comparison with alternatives like list_grc_risks or get_grc_risk. Minimal 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=true and openWorldHint=true. Description adds that it returns 'full details' and specifies identifier format, but no additional behavioral context beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action and resource, no wasted words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with good annotations and complete schema, the description is sufficient. It could mention return format, but not necessary given lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes the parameter, but description adds an example format (HRCS0001234) and clarifies the 'sys_id' option, enhancing understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get full details of an HR case' with specific identifier format (number like HRCS0001234 or sys_id). It distinguishes from siblings like get_hr_case_activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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_hr_case_activity, get_hr_profile, or list_hr_cases. Agent must infer 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?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds that results include tasks and SLAs, but does not disclose behavior on missing entities or ambiguous names. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action and resource, no wasted words. Highly concise and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of sibling list tools and the simple schema, the description adequately covers the tool's purpose. No output schema is needed, as return value is implied. Slight lack of usage context prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter, which already explains 'sys_id_or_name'. The description adds 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'HR service', and clarifies scope with 'including its tasks and SLAs'. This clearly distinguishes it from sibling tools like 'list_hr_services' and 'get_hr_case'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving details, but provides no explicit guidance on when to use this vs alternatives like 'list_hr_services' or 'search_hr_services'. No when-not or prerequisites 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. The description adds that it retrieves full details by number or sys_id, but does not disclose behavioral traits like returned fields, pagination, or rate limits. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the verb and resource, with no unnecessary words. It is perfectly concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 readOnlyHint, the description covers the essential purpose and input format. However, since there is no output schema, mentioning that it returns the complete incident object would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the parameter, but the description adds valuable examples (e.g., INC0012345) and clarifies that sys_id is also accepted. This goes beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get full details' and the resource 'incident', with explicit examples of valid inputs (INC0012345 or sys_id). This distinguishes it from other get_* tools like get_record, which might be more generic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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_record, search_knowledge, or natural_language_search. The description implies its use for incident retrieval but does not provide exclusions or 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=true and openWorldHint=true. The description adds that it includes CSS variables, but does not elaborate on response structure or any potential side effects. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with 12 words. Highly concise and front-loaded with the essential purpose and key detail (CSS variables).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (1 param, no output schema), the description adequately covers the tool's purpose and key output detail. However, without an output schema, describing return value format would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the single parameter 'sys_id' described as 'Theme sys_id'. The description does not add additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (Get), resource (portal theme), and scope (full details including CSS variables). Distinguishes from sibling tools like get_portal and list_portal_themes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the purpose, but no explicit when-to-use guidance or alternatives are mentioned. Sibling tools are numerous, but the description doesn't help the agent differentiate.
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 no additional behavioral context beyond stating it retrieves source code. No mention of side effects, authentication, or other traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that concisely communicates the purpose without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (single parameter, annotations, no output schema), the description adequately covers what the tool does. It could potentially mention the output format, but it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes the parameter. The tool description does not add any additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets full source code of a Service Portal widget, specifying the resource and details (HTML, CSS, scripts). It distinguishes from siblings like list_portal_widgets 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly provide when to use or when not to use this tool. It lacks guidance on alternatives or exclusions, though the name and context imply its 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?
Annotations already provide readOnlyHint=true and openWorldHint=true, indicating safe read and potential variability. The description adds no further behavioral context beyond what is implied, which is adequate 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/5Is 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. It is concise and contains no extraneous information, 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of a getter tool with one parameter, good annotations, and a sibling list tool, the description is mostly complete. It could mention that it returns the full record, but the agent can infer this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description is minimal ('Playbook or process name or sys_id'). The tool description adds no extra meaning beyond 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves details of a Process Automation Designer playbook or process. The verb 'Get' combined with the resource distinguishes it from sibling tools like list_process_automations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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 (e.g., list_process_automations for listing). While the purpose is clear, the description does not specify prerequisites or scenarios where this tool is preferable.
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 and openWorldHint. The description adds context about returning 'full configuration including endpoints', which is helpful but does not disclose additional behavioral traits beyond what annotations 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words. Highly concise and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 defines the scope (full configuration including endpoints). Some users might benefit from examples or return format hints, but the current description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the single parameter. The description does not add new semantic 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get full configuration of an outbound REST Message including its endpoints', specifying the verb (Get), resource (REST Message), and scope (full configuration with endpoints). This distinguishes it from sibling tools like list_rest_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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_rest_messages or get_record. Usage is implied by the purpose, but no when-not or alternative scenarios 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 include readOnlyHint=true and openWorldHint=true, which are consistent with the description's 'Get full details'. The description does not add behavioral context beyond the annotations, nor does it contradict them. With annotations present, the description is adequate 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the tool's purpose and input requirements. No extraneous information or repetition of structured fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (1 parameter, no output schema), the description covers the essential purpose and input. However, it lacks information about return behavior (e.g., whether 'full details' includes all fields) and error scenarios (e.g., what happens if the ID is not found).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with one parameter 'id' described as 'App sys_id or scope name'. The description adds a concrete example ('x_myco_myapp') that clarifies the expected format, providing value beyond the schema's own description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get full details'), the resource ('scoped application'), and the identification methods ('by sys_id or scope name'). It distinguishes itself from sibling tools like 'list_scoped_apps' and 'create_scoped_app' by specifying it retrieves one specific app by ID or 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/5Does 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 when to use 'get_scoped_app' over 'search_scoped_app' or 'list_scoped_apps'. There is no mention of prerequisites, typical scenarios, 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with annotations (readOnlyHint, openWorldHint) but does not add behavioral details beyond what the schema and annotations already provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is front-loaded with the key action and parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema), the description is fairly complete. However, it could mention that it returns the full record, but this is implied by 'Get full details'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds minimal meaning beyond the schema (it mentions 'number (SIR...) or sys_id' which is nearly identical to the schema description). 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get', the resource 'security incident', and the method of identification 'by number or sys_id'. It is specific and distinguishes itself from siblings like list_security_incidents or get_incident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for retrieving details of a single security incident, but does not explicitly state when to use this over siblings or provide 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 already declare readOnlyHint=true and openWorldHint=true. The description adds no behavioral context beyond stating it retrieves details, which is consistent but does not elaborate on aspects like pagination, access restrictions, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It conveys the essential information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema), the description is largely complete. However, it could mention that the record includes all fields, which is typical for a get operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description aligns with the schema's parameter description. No additional semantic value is provided beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'task record', and the method 'by number or sys_id'. It effectively distinguishes from sibling tools like get_incident or get_change_request which target specific subtypes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies general use for any task record but does not explicitly state when to choose this over specific task getters (e.g., get_incident). No alternative tools are mentioned or usage contexts discussed.
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 it's a safe read operation. The description adds that it returns layout and child elements, but no further behavioral details (e.g., response format, permissions). 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is clear and front-loaded. Every word is necessary; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with no output schema, the description mentions specific included details (layout and child elements), which gives the agent a reasonable expectation of the response. While more detail could be added, it is largely sufficient given the openWorldHint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the sole parameter 'sys_id'. The description does not add additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 resource ('UI Builder page'), specifying that it includes layout and child elements. This distinguishes it from sibling tools like list_uib_pages (list) and delete_uib_page (delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. Usage is implied (retrieve by sys_id), but no exclusions or when-not-to-use are mentioned. The context of siblings helps, but the description itself lacks 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. The description adds the scope of the details (intent and trigger phrases) but does not elaborate on any other behavioral traits like error handling or the structure of the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no unnecessary words. It is front-loaded with the core action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (single parameter, no output schema), the description adequately covers what the tool returns (topic details including intent and trigger phrases). It could be more comprehensive about potential additional fields, but the combination with annotations is sufficient 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter 'sys_id' is already documented. The description does not add extra meaning about the parameter format or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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', and specifies what is included ('intent and trigger phrases'). It distinguishes this from siblings like 'get_virtual_agent_topics' which is a list tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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. The context implies it is for a single topic by sys_id, but the description lacks any when-to-use or when-not-to-use directives.
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 a '[Write]' tag but no additional behavioral traits such as concurrency effects, rollback behavior, or permission requirements 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/5Is 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, with zero unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters and no output schema, the description covers the basic purpose and input format. It lacks details like error handling or behavior on duplicate keys, but overall it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and descriptions in schema are clear. The description adds 'from a JSON object' but does not significantly enhance understanding of parameters beyond the schema's existing detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Import (create or update)' and the resource 'system properties from a JSON object', distinguishing it from siblings like 'set_system_property' which sets a single property.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for importing multiple system properties but does not explicitly differentiate from alternatives like 'bulk_set_properties' or 'set_system_property', lacking when-to-use or when-not 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 describes the core functionality, but since annotations already declare readOnlyHint=true and openWorldHint=true, the description adds little new behavioral context. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the verb and resource. It is concise and contains no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the three parameters are fully documented and the operation is a simple list, the description is largely complete. It could mention pagination behavior, but this is partially covered by the limit parameter description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for all three parameters (limit, query, category). The description does not add meaning beyond the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 ('reusable Flow Designer action instances available in the environment'). It is specific and distinguishes this tool from similar list tools like list_flows or list_subflows by focusing on action instances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used to list action instances but provides no explicit guidance on when to use this over alternatives (e.g., list_flows). No when-not or comparative context 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?
Description is consistent with annotations (readOnlyHint, openWorldHint) but adds no extra behavioral context such as 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with parenthetical examples, no wasted words, verb first. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with well-documented parameters and annotations, the description is mostly complete. Missing explicit mention of return format (list of definitions with details) but still adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so parameters are fully described in the schema. The description does not add additional meaning beyond listing the resource type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'List' and resource 'Import Set data source definitions' with specific examples in parentheses, distinguishing it from siblings like 'list_import_sets'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies the tool is for data source definitions rather than import sets but does not explicitly state when to use it versus alternatives like 'list_import_sets' or 'get_import_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 declare readOnlyHint=true and openWorldHint=true. Description adds no extra behavioral details (e.g., pagination, ordering, or limitations). Adequate but minimal addition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 7 words, no waste, immediately clear purpose. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but purpose is simple. Could mention that it returns a list of event definitions, but context is mostly sufficient for a basic list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters (limit, query) with descriptions. Description does not mention parameters, adding no value beyond schema. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List registered event definitions in the ServiceNow event registry', specifying verb, resource, and context, distinguishing it from siblings like 'list_event_log' and 'get_event_registry_entry'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs. alternatives like 'register_event' or 'get_event_registry_entry'. Usage is implied by the purpose but not 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 indicate readOnlyHint=true and openWorldHint=true, so the description need not add much. The description merely restates that it lists templates, adding no new behavioral traits 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys the tool's purpose efficiently without extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (list with optional filters), the description is mostly complete. However, there is no hint about pagination or return format, which could be useful. But the annotations and schema compensate sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and all parameters have descriptions. The description adds examples of template types but does not enhance understanding of the parameters' meaning or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List), the resource (HR document templates), and provides examples (offer letters, contracts, policies), making it unambiguous. It also distinguishes this tool from other list tools by specifying the HR document domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing HR document templates but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. Sibling tools include many other 'list' functions, so more context would 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 provide readOnlyHint (true) and openWorldHint (true). The description adds no additional behavioral traits beyond what annotations offer, so it is adequate 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that immediately conveys the tool's purpose. There is no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and full schema/annotation coverage, the description is adequate. It does not detail pagination or response structure, but the context signals indicate no output schema, so this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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. The description does not add 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (list), the resource (HR tasks), and the context (associated with an HR case). It is specific and distinguishes from sibling tools like list_hr_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating what it does but does not provide explicit guidance on when to use it vs alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, covering the safety profile. The description adds no additional behavioral context such as pagination, ordering, or result limitations. Given annotations, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-constructed sentence with no filler. It is front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 largely complete. It could mention that results might be paginated or filtered, but overall it provides sufficient context given the tool's simplicity and the annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully describes the parameters. The description does not add any extra meaning or context for the parameters beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the specific resource 'OAuth application registry entries' with a clarifying parenthetical. It distinguishes well from sibling list_ tools that target different entities like users or 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/5Does 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. The context of a simple list operation is implied, but there is no mention of when not to use it or how it compares to other listing 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 provide readOnlyHint and openWorldHint, indicating a safe read operation. The description adds minimal behavioral context beyond clarifying the resource type. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a clear action verb 'List', resource 'Service Portal themes', and parenthetical examples. No unnecessary words, perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 and no output schema, the description is sufficiently complete. It could potentially mention the return format (array of theme objects) but the name and context imply that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'limit' clearly described. The tool description does not add any additional meaning to the parameter beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it lists Service Portal themes and clarifies what themes are with examples 'color palettes, CSS variables'. This specific verb+resource clearly distinguishes from sibling tools like 'get_portal_theme' which retrieves a single theme.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing themes but does not explicitly state when to use it vs alternatives like 'get_portal_theme' for a single theme. No guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the description's 'List' is consistent. No additional behavioral traits are disclosed beyond what the schema and annotations provide. The description does not add context about pagination or default behavior beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short, front-loaded sentence with no waste. Every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with good annotations, the description is adequate. It could mention the return format or what constitutes a 'configuration', but the overall context is sufficient for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description does not add extra meaning beyond what the schema's descriptions (e.g., 'Max records to return') already offer. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the specific resource 'outbound REST Message configurations (integrations with external APIs)'. It effectively distinguishes this tool from siblings 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing configurations but does not explicitly state when to use this tool versus alternatives like list_rest_message_functions or get_rest_message. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- 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 no extra behavioral context beyond listing and filtering, but 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no waste, but could be slightly more structured (e.g., indicating return type). Still efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema and 5 parameters, the description is minimal but covers the core function. Missing details like pagination or default sort order, but adequate with annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-defined. The description mentions three filters (severity, state, category) but does not add meaning beyond the schema for limit and query.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists security incidents with specific filters. The resource is distinct from siblings like list_incidents or get_security_incident, making 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use when listing security incidents with filters. It does not explicitly exclude alternative tools like get_security_incident for single incidents, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint=true annotation already declares this as a read-only operation, and the description aligns ('list'). The description adds value by specifying this is scoped to 'Local sync' capabilities and that it returns both artifact types AND field-sync mappings, which is useful behavioral detail beyond the annotation. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that conveys scope (local sync), resource (artifact types/tables), operations (pull/push), and the field-sync detail in one line. There's no wasted wording, and it's front-loaded with the 'Local sync' qualifier which is the most important disambiguator.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 readOnly annotations covering the safety profile, the description provides adequate completeness. It covers what data is returned (artifact types + syncing fields), but doesn't mention return format, pagination, or whether output varies by instance. For a capability-discovery tool this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so there's nothing for the description to elaborate on. The description's mention of returning 'which fields sync for each' artifact type provides useful context about what the response will contain, effectively substituting for lacking an output schema. A baseline of 4 is appropriate for a zero-parameter read tool where the description clarifies the response content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: lists artifact types (tables) supporting pull/push to local files and which fields sync for each. The verb 'list' plus the resource 'supported_artifacts' with the 'local sync' context makes the purpose clear. It distinguishes from siblings like pull_artifact/push_artifact by focusing on the capabilities listing rather than the operation itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys that this is used in the 'Local sync' context, which implies it's meant to be called before pull/push operations to discover what's supported. However, it doesn't explicitly state when to use this vs alternatives like sync_status or pull_artifact, nor does it give explicit when-not guidance. The context is implied but not fully 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 does not add behavioral traits beyond what annotations already provide (readOnlyHint, openWorldHint). It lacks details on pagination, response format, or any constraints, but annotations cover the read-only nature adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the action and resource, with no unnecessary words or structure issues.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with three optional parameters, the description covers the core purpose and the schema documents parameters well. However, it lacks context on common use cases (e.g., before importing data) or pagination behavior, but is still fairly complete 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no additional parameter meaning. It does not elaborate on how parameters interact or provide usage examples, keeping it at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'Transform Maps' with the context 'used for importing data into ServiceNow tables,' making the tool's purpose unambiguous and distinguishable from siblings like get_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/5Does 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. The usage context is implied by the resource name, but no when-not-to-use 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?
Annotations indicate a write operation (readOnlyHint=false) with side effects (openWorldHint=true). The description adds the requirement WRITE_ENABLED=true but does not disclose further behavioral details like state changes or irreversibility. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that efficiently communicates the tool's purpose and a key requirement. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with three parameters and no output schema, the description is largely complete. It could mention the effect on the problem state, but it is still sufficient for an AI agent to understand the tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions for each. The description does not add 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Resolve' and resource 'problem', specifying the action and the inputs (root cause and resolution notes). It distinguishes from sibling tools like 'update_problem' (update vs resolve) and 'close_incident' (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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (requires WRITE_ENABLED=true) but does not provide guidance on when to use this tool versus alternatives like update_problem or close_incident. Usage 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 declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a write operation that is not destructive. The description adds the WRITE_ENABLED requirement, which is useful. However, it does not disclose whether the tool is idempotent (idempotentHint=false is provided but not explained), what happens on repeated execution, or if it can partially fail. Some behavioral 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the main action and a key prerequisite. It is front-loaded with the essential verb and resource, and every word adds value. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description should explain what the tool returns (e.g., success status, loaded record count, or error details) and provide more context on side effects or execution behavior. The description only mentions 'load data' without specifying outcomes or potential failures, which is insufficient for a complex transformation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter descriptions in the schema are clear. The description adds no additional meaning beyond the schema, so it meets the baseline expectation but does not enhance understanding of the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Execute a Transform Map'), the resource ('Import Set'), and the goal ('to load data'). It distinguishes from sibling tools by specifying a unique operation not duplicated elsewhere, and includes a critical prerequisite (WRITE_ENABLED=true). This provides a precise 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a clear requirement (WRITE_ENABLED=true) that guides when the tool can be used. However, it does not explicitly state when to use this tool versus alternatives (e.g., import_cmdb_data) or when not to use it. The context is sufficient but lacks 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 and openWorldHint. The description adds that the search matches against specific fields but does not elaborate on behavioral traits like pagination, rate limiting, or incomplete results. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that succinctly conveys the tool's purpose. Every word adds value, and it is 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with two well-documented parameters and no output schema, the description adequately covers the core functionality. However, it could mention the open-world nature hinted by the annotation to be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already documents both parameters. The description does not add additional meaning or clarify expected formats 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and resource 'system properties', and specifies the matching fields (name, value, description). This distinguishes it from sibling tools like list_system_properties (which lists all) and get_system_property (which retrieves a specific one).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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. It implies usage for searching but lacks guidance on when not to use or which sibling to prefer (e.g., list_system_properties for full list, get_system_property for single property).
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 'test input' context but does not disclose potential side effects, rate limits, or error conditions beyond the prerequisite. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the action and prerequisite. 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema covers both parameters and annotations are present, the description is sufficiently complete. It includes a prerequisite not captured elsewhere. However, it could briefly mention the return value or error handling, but the lack of output schema reduces the need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description reiterates the schema's parameter names ('test input', 'skill system ID') without adding additional semantics or format details, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('invoke a Now Assist skill with test input') and the purpose ('to verify behavior'), distinguishing it from sibling tools like create_now_assist_skill or get_now_assist_skill.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the prerequisite 'requires NOW_ASSIST_ENABLED', providing some context, but lacks explicit guidance on when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, setting the safety and output expectations. The description adds that it returns trend data bucketed by time, but does not disclose additional behaviors like aggregation method, return format, or pagination. Since annotations already cover core behavioral traits, the description provides marginal 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single succinct sentence that immediately communicates the tool's purpose and use case. It is front-loaded with the core action and resource, with no superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (3 required) and no output schema, the description covers the main use case for trend charts. However, it omits details such as default period count and the nature of the trend data (e.g., count of records per bucket). With openWorldHint=true, some omission is acceptable, but slight improvement would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter documented. The description does not add new semantics beyond what the schema provides; for example, 'date_field' is described in both. Thus the description adds no additional meaning, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this tool retrieves 'time-bucketed trend data' for a table, with a specific use case for trend charts. It uses a specific verb 'Get' and defines the resource type (trend data), clearly distinguishing it from sibling query tools like query_records or run_aggregate_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description suggests using it for monthly/weekly trend charts, providing a clear use case. However, it does not offer when-not-to-use guidance or explicitly compare to alternative tools for similar purposes, relying on implicit understanding.
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's not read-only, not destructive, and idempotent. The description adds the WRITE_ENABLED requirement, which is useful context, but does not disclose further behavioral traits like access control 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a parenthetical on requirements, conveying the core purpose efficiently without extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, schema coverage 100%, no output schema), the description adequately covers purpose and a key prerequisite. It lacks detail on return value or error conditions, but those are not critical for a simple update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description mentions the same fields listed in the schema's parameter descriptions. It adds no 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('vulnerability entry'), listing specific fields (state, risk acceptance notes, remediation date), which distinguishes it from other update tools targeting different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('requires WRITE_ENABLED=true'), providing some context, but does not explicitly state when to use this tool versus alternatives (e.g., other update tools) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- 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 statement 'without saving' adds confirmation but no new behavioral traits. It does not mention auth requirements, rate limits, or error behavior. With annotations present, the bar is lower, and the description 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that immediately conveys the tool's purpose and key trait (no saving). It is concise with no unnecessary words, earning a top score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 simple string params) and no output schema, the description is mostly complete. However, it lacks any explanation of the return value (e.g., boolean, errors), which would be helpful for an agent to understand what to expect from validation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add any additional information about the 'name' and 'value' parameters beyond what the schema already provides. It mentions 'declared type constraints' generically, but does not elaborate on parameter-specific details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Validate' with the resource 'property value' and specifies 'without saving', clearly distinguishing it from other property tools that modify or save. This directly differentiates it from sibling tools like 'set_system_property' and other validators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for dry-run validation but does not explicitly state when to use this tool over alternatives like 'validate_artifact' or 'set_system_property'. No when-not or alternative guidance is provided, though the context of 'without saving' gives a clear usage hint.
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 explains that this tool works through the Table API analyzing similar resolved incidents, which is a heuristic approach as opposed to a model-based one. It discloses the limitation that PI has no public REST prediction endpoint, giving the agent important context about what this tool does and does not do. With readOnlyHint=true and openWorldHint=true annotations already present, the description adds meaningful behavioral nuance about the heuristic mechanism and PI limitation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence that efficiently conveys purpose and key limitation without redundancy. The PI limitation note is relevant and earns its place. Slightly more structure could help, but the density of useful information is high with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 100% schema coverage, readOnly/openWorld annotations, and no output schema, the description adequately covers the heuristic approach, the PI limitation, and expected outputs (category, assignment group, priority). It doesn't describe return format, but without an output schema and with the outputs named, this is acceptable completeness for a suggestion-type tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (short_description and description) are documented in the schema. The description adds minor value by noting that description is 'not required for the heuristic' and that short_description is the primary input. This clarifies the minimal input needed but doesn't go beyond what the schema already provides in terms of parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool suggests category, assignment group, and priority for an incident by analyzing similar resolved incidents via Table API. The verb 'suggest' combined with the three specific outputs (category, assignment group, priority) gives a clear purpose that distinguishes it from sibling incident tools like resolve_incident or close_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful context about what to use instead - it explicitly notes that Predictive Intelligence has no public REST prediction endpoint, and for model-based scoring the agent should run PI on-record and read the predicted field. This offers practical guidance for when alternatives are needed, though it doesn't fully spell out when to choose this tool versus the ml_auto_categorize or ml_similar_incidents sibling 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?
Annotations already declare readOnlyHint=true and openWorldHint=true, indicating a safe read operation. The description adds behavioral context by stating it 'returns percentage of non-empty values per field', which clarifies the output format 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the purpose and output. Every word is necessary, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and no output schema. The description omits details about the return format (e.g., mapping of field to percentage) and how sample_size affects the results. While the purpose is clear, the description could be more complete for an agent to fully understand behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. The description does not add significant meaning beyond the schema; it mentions 'per field' but that is already implied by the 'fields' parameter. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Analyze' and the resource 'data quality and field completeness for a ServiceNow table', with specific output 'percentage of non-empty values per field'. It distinguishes from siblings like analyze_data_quality by focusing on field-level completeness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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 like analyze_data_quality or get_table_schema. No when-to-use or when-not-to-use language is present, leaving the agent to infer based on 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint. The description adds context about analyzing downstream impact of change/outage, which is useful beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the verb and resource. Every word is necessary, with no wasted information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal for a tool of moderate complexity. There is no output schema, and the description does not explain the return format (e.g., list of affected CIs, graph). The parameters are well-documented in schema, and annotations provide safety hints, but more output context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters clearly. The description adds no additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Analyze' and the specific resource 'downstream impact of a Configuration Item change or outage'. It distinguishes from sibling tools like cmdb_find_duplicates or cmdb_health_dashboard, 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for understanding downstream impact of a CI change or outage, but does not explicitly state when to use this tool versus alternatives, nor provide when-not scenarios. Usage is implied but not fully specified.
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 write operations (readOnlyHint=false), and description aligns by stating 'Create'. However, beyond the prerequisite, the description adds no behavioral context such as side effects (e.g., whether creation can block access), return value, or potential conflicts. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that wastes no words. It conveys the primary purpose and a critical prerequisite in a compact format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of ACL creation (8 parameters including roles, script, admin_overrides), the description is minimal. It lacks explanation of return value (since no output schema exists) and typical usage patterns. It covers the basic purpose but leaves agents to rely heavily on the schema and implicit knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all 8 parameters documented). The description adds no extra meaning beyond the schema—it only mentions 'ACL rule to control access to a table or field', which is a high-level summary. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new ACL rule to control access to a table or field', which specifies the verb (create) and resource (ACL rule). It distinguishes itself from sibling tools like 'update_acl' and 'list_acls' by focusing on creation. The prerequisite 'requires SCRIPTING_ENABLED=true' 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions a prerequisite (SCRIPTING_ENABLED=true), providing important context for when to use the tool. However, it does not explicitly state when not to use it or mention alternatives. The context with siblings like 'get_acl' and 'update_acl' implies usage scenarios, but direct guidance is missing.
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 prerequisite flags (NOW_ASSIST_ENABLED, WRITE_ENABLED), which is useful context. However, it does not disclose other behavioral traits such as whether the workflow is immediately active, if it triggers any side effects, or how to handle errors. The description 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently communicates the core purpose and a key requirement. It is front-loaded and contains no unnecessary words, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description mentions important prerequisites, but given the tool has 5 parameters including a nested array (steps), and no output schema exists, the description should ideally indicate what the tool returns (e.g., the created workflow's sys_id). Without this, the agent may lack guidance on how to use the output. However, the schema descriptions partially compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the baseline is 3. The tool description does not add any further explanation of parameters beyond the schema. Thus, it meets the baseline but does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create an agentic workflow linked to an AI agent'. It uses a specific verb-resource combination ('Create an agentic workflow') and distinguishes from sibling tools like create_flow or create_subflow by specifying 'agentic' and 'linked to an AI agent'. It also mentions required privileges, further clarifying its 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context by stating the required privileges ('requires NOW_ASSIST_ENABLED + WRITE_ENABLED'), which hints at when it should be used. However, it does not explicitly compare to alternatives like create_flow or create_ai_agent, leaving the 'when to use vs when not to use' somewhat 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?
Adds value beyond annotations by specifying the WRITE_ENABLED permission requirement. Annotations already indicate write operation, non-idempotent, non-destructive; description supplements with 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence with no wasted words. Front-loads purpose and constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks details on return value, error conditions, or duplicate handling. Adequate for a simple create tool but could be more complete given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions; description adds no extra meaning. 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/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Create' and resource 'assignment group', with a prerequisite (WRITE_ENABLED=true). It distinguishes from generic create tools and sibling '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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions a requirement but lacks explicit guidance on when to use vs other create tools (e.g., create_user, create_incident). Minimal context for selection among many 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 (readOnlyHint=false, destructiveHint=false) already indicate a non-read, non-destructive write operation. The description adds the 'requires WRITE_ENABLED=true' constraint, providing useful behavioral context beyond annotations. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. It efficiently conveys the core purpose and a key prerequisite.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could mention return value (e.g., sys_id of created task) or validation behavior. It covers the essential context but lacks completeness for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description does not add any parameter-specific meaning 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and resource (task within an HR case), using a specific verb and resource. It distinguishes from siblings like create_hr_case by specifying the parent context. The precondition 'requires WRITE_ENABLED=true' adds 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating tasks under an HR case but does not explicitly state when to use this tool versus alternatives like create_hr_case or update_hr_case. No explicit when-not-to-use 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?
The description adds a concrete prerequisite (NOW_ASSIST_ENABLED + WRITE_ENABLED) beyond what annotations provide. Annotations already indicate it's writable and non-destructive, and the description supplements with a permission requirement. However, it does not detail other behaviors like idempotency 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, no unnecessary words. The requirement info is front-loaded in parentheses, making it efficient for an agent to quickly grasp the purpose and constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple creation tool but lacks information about the return value (no output schema), synchronization, or error scenarios. Given the complexity of the tool (6 parameters, 5 required), more context would improve agent usability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add any additional meaning beyond the parameter names and types already in the schema. No extra context for usage of each parameter is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a Now Assist skill definition', using a specific verb and resource. It distinguishes from sibling tools like list_now_assist_skills, get_now_assist_skill, and test_now_assist_skill by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating a new skill but does not explicitly state when to use or when not to use this tool over alternatives. No mention of prerequisites beyond the requirements in parentheses, and no comparison to similar create 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?
Annotations already indicate readOnlyHint=false, making clear this is a write operation. The description adds valuable behavioral context: it notes the WRITE_ENABLED requirement and the need for a subsequent PA job to collect data, which annotations do not cover. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose and requirement. Every clause adds value: action, resource, condition, what to define, and post-creation step. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should cover what the tool returns. It mentions the need for a PA job but does not state what the response contains (e.g., sys_id). For a creation tool with 9 parameters, this is a gap, though the core concept is explained adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions (e.g., field, aggregate, conditions). The description mentions 'source facts table, aggregation and conditions', but adds little beyond the schema. For a tool with full 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Create'), the resource ('Performance Analytics indicator / KPI'), and includes context like the table name and a required configuration setting (WRITE_ENABLED=true). It distinguishes from sibling tools like create_pa_breakdown by focusing on indicator creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context (requires WRITE_ENABLED=true and mentions post-creation job), but lacks explicit guidance on when to use this tool vs. alternatives like create_pa_breakdown or create_kpi. No exclusions or when-not-to-use 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 indicate a write operation (readOnlyHint=false). The description adds the WRITE_ENABLED requirement but does not elaborate on consequences like error handling or side effects. Minimal additional disclosure 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose. No unnecessary words. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a create tool with 8 parameters and no output schema. Mentions a key prerequisite and constraint, but does not describe return values, error cases, or what happens upon successful creation. Missing some contextual completeness given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 a slight refinement for the scope parameter (pattern x_<vendor>_<appname>), but otherwise does not explain parameter behavior beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Create a new scoped application in App Studio', specifying the action, resource, and context. Distinguishes from siblings like update_scoped_app and list_scoped_apps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a prerequisite (WRITE_ENABLED=true) and a constraint (scope prefix must be unique and follow pattern), offering good usage context. Does not explicitly state when not to use or list alternatives, but the sibling tools imply the distinction.
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, non-idempotent behavior. The description adds the WRITE_ENABLED requirement, which is beyond annotations. However, it does not disclose other behaviors like validation failure handling, auto-numbering, or side effects (openWorldHint=true suggests potential side effects). The contribution 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 13 words, efficiently stating the purpose and a key requirement. It is front-loaded and free of any extraneous information, earning full marks for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with no output schema, the description is minimally adequate. It does not explain return values, behavior on missing optional parameters, or potential side effects. Given the tool's simplicity and the richness of sibling tool names, the description could provide more context but does not miss critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 (assigned_to, story_sys_id, short_description). The tool description itself adds no additional parameter semantics beyond what the schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a scrum task, specifying it is a sub-task of a story. This distinguishes it from other create tools like create_story or update_scrum_task. The verb "create" and resource "scrum task" are 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a requirement (WRITE_ENABLED=true) and identifies the parent-child relationship (sub-task of a story), giving context for when to use. It implies usage for creating a task under a story, but does not explicitly state when not to use or mention alternatives. The requirement adds clear guideline.
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=true and openWorldHint=true. The description adds context about output features (branding, charts, tables, ServiceNow links) and the two usage modes. No contradictions are evident; the tool likely does not modify persistent state. Value added 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: first states purpose and formats, second provides context for invocation, third explains usage modes. No redundant information, efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and moderate complexity, the description covers the essential workflow. It could mention prerequisites (e.g., must have capability analysis results) or constraints (e.g., size limits), but it suffices for a management-ready report tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 meaning by explaining the relationship between 'content' (single capability) and 'sections' (multiple capabilities), clarifying the dual usage pattern beyond the schema's individual descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a branded PDF or PPTX report from capability analysis results. It differentiates from most siblings by focusing on report generation, but does not explicitly distinguish from 'create_report' or 'scheduled_report' which might overlap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Call this after completing a scan, review, or audit', providing when to use. However, it does not mention when not to use or alternatives like 'create_report' or 'scheduled_report', leaving the agent without 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 and openWorldHint=true, so the description adds limited behavioral context. It mentions returned metadata fields (name, type, size) but does not disclose behavior for invalid sys_id or potential additional fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys the essence without superfluous words. It is front-loaded with the core action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, read-only, no output schema), the description adequately covers the purpose and expected return data. No additional context is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'attachment_sys_id' described as 'Attachment sys_id'. The description's phrase 'by its sys_id' adds no new meaning beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get), resource (metadata), and specific fields (name, type, size) for a single attachment identified by sys_id. It differentiates from siblings like list_attachments or upload_attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an attachment sys_id, but it does not explicitly state when to use it versus alternatives (e.g., list_attachments for multiple, or get_record for full attachment data). No when-not 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 and openWorldHint=true, so the description adds little beyond confirming read-only behavior via the scripting requirement. However, it does not explain what 'details' implies or address openWorldHint's implication of external interactions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, single sentence with no wasted words. Front-loaded with purpose and condition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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, the description provides purpose and a prerequisite. However, it does not describe the return value (output) since there is no output schema, leaving some ambiguity about what 'details' includes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (sys_id_or_name described as 'Update set sys_id or name'), so the description adds no additional meaning beyond the schema. 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/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get details of an update set' with a specific verb and resource. Distinguishes from sibling tools like list_changesets (list) and commit_changeset (commit), and adds a context constraint (SCRIPTING_ENABLED=true).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states a prerequisite condition (requires SCRIPTING_ENABLED=true), providing clear context for when to use. Does not explicitly mention alternatives or when not to use, but the condition effectively guides 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?
Annotations provide readOnlyHint and openWorldHint. The description adds that the result includes the formula, which is a useful behavioral detail beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no filler, directly states purpose and key detail (formula). Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter tool with one parameter and no output schema, the description is sufficient. It covers the purpose and a key behavioral detail (formula).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter. The description does not add extra meaning beyond the schema's 'Indicator sys_id or name'. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets details of a specific Performance Analytics indicator, including its formula. It distinguishes from sibling tools like list_pa_indicators (list) and other get_pa_* tools (different entities).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. However, the readOnlyHint implies it's for reading, and the sibling list_pa_indicators complements it. Usage 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable context: the PA plugin requirement and the widget-to-indicator resolution behavior, and the underlying API endpoint. It doesn't fully disclose return format or pagination behavior, but with the annotation coverage the bar is reasonably met.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact at roughly two sentences and front-loads the core purpose. Every clause earns its place—plugin requirement, API endpoint, and the two input modes are all useful. Slightly dense but appropriately sized for a read tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no required parameters, no output schema, and 100% schema coverage, the description does a reasonable job. It explains the plugin prerequisite and the widget-resolving behavior which are non-obvious. Could add note about behavior when both/neither param is passed, and how results are returned, but it's fairly complete for a straightforward read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all 4 parameters well documented. The description adds the key relationship between widget_sys_id and indicator_sys_id (widget resolves to indicator), which adds value. However, it doesn't clarify expected output format or behavior when both parameters are provided or neither is provided, leaving some ambiguity at the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 via a specific API endpoint. It provides a distinct verb + resource (read PA data) that helps differentiate it from siblings. However, it doesn't explicitly distinguish itself from closely related sibling tools like get_pa_indicator, get_pa_dashboard, get_pa_time_series, which it overlaps with.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: requiring the PA plugin, and explains the two input modes (pass indicator sys_id, or PA widget sys_id to resolve its indicator). It doesn't explicitly state when NOT to use this vs alternatives like get_pa_indicator or get_pa_time_series, which would be the main 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. The description adds context about 'recent' executions and possible statuses, but does not provide extensive behavioral details 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with key information, no unnecessary words. Every part 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.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a list operation with 3 parameters and no output schema. It lacks detail on return format, ordering, or pagination behavior, but annotations provide some context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description does not add significant meaning beyond schema. It mentions 'recent' executions but does not elaborate on parameter details beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'flow executions', and includes filters by status. It distinguishes between siblings like 'get_flow_execution' (singular) and 'list_flows' (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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing executions of a specific flow with status and limit filters. It does not explicitly provide when-not-to-use or mention alternatives, but the context is clear given 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 description aligns with the readOnlyHint annotation, confirming it is a safe read operation. However, it does not add any behavioral context beyond the annotations, such as pagination behavior, default limit, or what 'list' returns (e.g., all controls or only active ones). With annotations already covering the safety profile, 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/5Is 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. Every word is necessary, and there is no verbosity. It is extremely concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and three parameters, the description could provide more context, such as what the return format looks like or pagination details. It is minimally adequate but leaves gaps for a complete understanding of the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 description adds that filters are optional and mentions 'risk or policy', but 'policy' is not a parameter in the schema (only state and risk_sysid). This is a minor inaccuracy, and overall the description adds limited value beyond the schema, warranting a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'GRC controls', and mentions optional filters by risk or policy, making the tool's purpose immediately apparent. It distinguishes well from sibling tools like list_grc_risks or list_compliance_policies by focusing on controls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use the tool (to list GRC controls with optional filters), but does not explicitly state when not to use it or provide alternatives among the numerous list tools. It is clear in context but 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=true and openWorldHint=true, which the description does not contradict. The description adds minimal behavioral context beyond stating it lists cases; it does not explain output format, pagination, or error handling. With annotations carrying the safety profile, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys purpose and available filters without extraneous information. It is appropriately front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal but functional for a simple list operation. It does not explain return values (no output schema), defaults (though schema mentions limit default), or behavior when no filters are provided. Given the tool's simplicity, it is adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning each parameter is already documented in the schema. The description adds no new meaning beyond repeating the filters, which overlaps with schema descriptions. Baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 explicitly lists the optional filters (status, subject person, service). It distinguishes itself from sibling tools like get_hr_case or search_tools by its specific listing 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to list HR cases with filters) but does not provide explicit guidance on when not to use it or suggest alternatives. Given the extensive sibling list, a brief mention of suitable contexts would improve clarity, but the current description is still clear enough for the core use 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 provide readOnlyHint and openWorldHint. The description adds that the scope is the currently configured user. It does not disclose behavioral traits like pagination, ordering, or rate limits, which would be helpful for an agent to understand results handling. The description does not contradict any 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core action and subject, with no unnecessary words. It is concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 and no output schema. The description covers the basic purpose but lacks details on result ordering, pagination, or return structure, which would be helpful for completeness. Given the tool's complexity, it is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 'limit', including its default value. The description does not add any further 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists tasks assigned to the currently configured user, using a specific verb (list) and resource (tasks) with a clear scope. It distinguishes itself from sibling list tools like 'list_approvals' or 'list_hr_cases' by focusing on the current user's tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying the intended user (currently configured user). While it does not explicitly state when not to use this tool or mention alternatives, the context is clear enough for most scenarios. A slight improvement would be to contrast with other task listing tools like 'get_task'.
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' verb is consistent. The description adds no further behavioral details beyond what annotations provide, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, front-loading the core purpose and optional search. It is highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with full schema coverage and readOnly annotation, the description is mostly adequate. It does not mention pagination or the default behavior when no query is provided, but these may be inferred from the schema's default limit value. Minor gaps, but sufficient for an experienced user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. However, the description mentions search by 'name or category' while the schema says 'Search widgets by name or description', creating a discrepancy that could mislead an AI agent about the actual search fields. This reduces the added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List Service Portal widgets' with a specific verb and resource, plus optional search. This effectively distinguishes it from sibling tools like 'get_portal_widget' (single retrieval) 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions optional search by name or category, providing context for when to use the search parameters. However, it does not explicitly state when not to use this tool or mention alternatives like searching via other 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?
Annotations already declare readOnlyHint and openWorldHint. The description adds context by explaining what UI Policies govern and the scripting requirement, beyond what the annotations 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the purpose and prerequisite. No unnecessary words or redundancies.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the tool's purpose and prerequisite but does not describe the return format, pagination, or ordering of results. Given no output schema, this omission reduces completeness for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to elaborate on parameters. It adds no additional meaning beyond the schema field descriptions, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool lists UI Policies for a table and clarifies what UI Policies control (field visibility, mandatory, read-only rules), distinguishing it from sibling list tools that target different entities (e.g., ACLs, business rules). The prerequisite note 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a clear prerequisite (SCRIPTING_ENABLED=true) indicating when the tool is usable, but does not provide guidance on when to avoid it or suggest alternative tools for related tasks like listing client scripts or ACLs.
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 hints. The description adds value by specifying it queries the last 500 resolved records and matches keywords, providing concrete behavioral context beyond the annotations. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the purpose and method without unnecessary words. It is well-structured and front-loaded with the main action. Could be slightly improved with bullet points or structured formatting.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema, the description covers the core functionality: analyzing records and suggesting a category. It does not discuss edge cases or return format, but that is acceptable given the tool's simplicity and high schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description mentions 'short_description' for keyword matching and 'description' optional for accuracy, but this does not add significant meaning beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('auto-categorize') and resource ('record'), and clearly explains the method: analyzing resolved records of the same table and matching keywords. This distinguishes it from siblings like 'categorize_incident' which may not use historical analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for automatic categorization based on historical data but does not explicitly state when to use this tool over alternatives like 'categorize_incident' or 'ml_similar_incidents'. No 'use when' 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, so the safety profile is already conveyed. The description adds meaningful context beyond this: it clarifies this returns editable fields for local editing, mentions behavior when NOWAIKIT_SYNC_DIR is set (writing one file per field and returning paths), and distinguishes this from update-set export. This enriches the read-only picture with concrete behavioral specifics. However, it doesn't disclose what happens to the fetched content or whether local writes are then synced back, and the local-sync side-effect behavior is somewhat under-specified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact three-sentence block that front-loads the core purpose ('Local sync: fetch an artifact's editable fields') before covering the conditional sync-dir behavior and clarifying what this is NOT. Every sentence earns its place, with the distinction-from-update-set clause preventing misuse. It is efficient and well-structured with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 fully-documented parameters, no output schema, and the sibling complement (push_artifact, sync_status, find_artifact, list_supported_artifacts), the description adequately explains the flow for a read operation. It covers the return content, the optional file-writing side effect, and the artifact-scope nature. The complexity is moderate and this description addresses the key use-case and the now-kit sync variant. There is no output schema so return value handling is reasonably implicit from 'returns content inline' and 'returns the paths'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents both parameters completely (table as artifact table with examples sp_widget/sys_script_include, sys_id as ID or resolvable name). The description adds framing context around these ('editable fields (e.g. template/css/script)') but the parameter semantics themselves are fully handled by the schema. Baseline 3 applies since the description goes slightly beyond by giving artifact examples and illustrating what editable fields means.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The purpose is clearly stated with a specific verb+resource ('Local sync: fetch an artifact's editable fields...for local editing'). It distinguishes itself from sibling write tool push_artifact and from update-set export. It also clarifies the artifact type (e.g. Service Portal widget) which helps differentiate from get_script_include/get_business_rule (which fetch full objects vs editable fields in sync context). This 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it is for 'config/pro-code editing of a single artifact' and explicitly contrasts with update-set export ('not an update-set export'). This implies use when one wants local editing of a single artifact, distinct from broader sync flows. However, it does not explicitly discuss when to choose this over get_script_include, get_business_rule, or get_portal_widget, nor when to use push_artifact (the reverse), find_artifact, or validate_artifact. The conditional NOWAIKIT_SYNC_DIR behavior offers context but no explicit alternatives or exclusions for sibling fetch tools. Adequate but with room to be more 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 indicate idempotent and non-destructive. Description adds the WRITE_ENABLED requirement, which is useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that efficiently conveys purpose and a key prerequisite. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic purpose and a requirement, but does not explain the fields object structure, return value, or how it differs from update_record. Given the tool's simplicity, it is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description's parameter information ('Fields to update (name, short_description, price, active, category, etc.)') is identical to the schema's field description, so no additional meaning is added. Schema coverage is 100%, baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it updates an existing catalog item, distinguishing from create operations. The required permission is also mentioned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides a required permission (WRITE_ENABLED=true) but does not give guidance on when to use this tool versus other update tools like update_record or create_catalog_item. Context is implied by name 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 readOnlyHint=false (write operation), destructiveHint=false (not destructive), and idempotentHint=true (safe to retry). The description adds the WRITE_ENABLED prerequisite, which is useful but does not elaborate on side effects, rate limits, or what exactly happens on update. Since annotations cover the safety profile, the description provides marginal 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words that is front-loaded with the action and resource. It efficiently conveys the essential purpose and a key prerequisite without any redundant or unnecessary text. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward update tool with no output schema, the description is minimally adequate. It identifies what is being updated and a necessary condition. However, it does not describe the return format, whether the update takes immediate effect, or how errors are handled. Given the lack of output schema, more completeness would be beneficial but not critical for this simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters (sys_id and fields are well-documented). The description adds no additional parameter-level details beyond the schema. Therefore, the description contributes no extra meaning for the parameters, warranting a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'email notification', and includes a prerequisite 'requires WRITE_ENABLED=true'. This distinguishes it from sibling tools like create_notification (create) and get_notification (read), making the purpose 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('requires WRITE_ENABLED=true'), which provides clear context for when the tool is usable. However, it does not explicitly state when not to use this tool or suggest alternatives (e.g., using create_notification for new notifications). Still, the context 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?
Annotations already indicate a write operation (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive. The description adds the WRITE_ENABLED=true requirement, which is valuable contextual information 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the action and a key prerequisite. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool has no output schema, the description omits details about the return value (e.g., the updated report object) and error handling. Annotations provide some behavioral hints, but the description could be more complete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters (sys_id, fields). The description does not add any additional meaning or examples beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and resource 'existing saved report definition', distinguishing it from siblings like create_report, get_report, and list_reports. It also mentions a prerequisite (WRITE_ENABLED=true), further specifying 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating saved reports and includes a prerequisite, but does not explicitly state when to use this tool over alternatives (e.g., create_report for new reports, delete_record to remove). No 'when-not' 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=false, destructiveHint=false, and idempotentHint=true, establishing basic behavior. The description adds the WRITE_ENABLED requirement, but does not disclose other side effects (e.g., audit logging) 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence that efficiently conveys the core purpose and a key prerequisite. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and the presence of a nested object parameter, the description lacks information about return values or update effects. It is 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have descriptions in the input schema (sys_id and fields). The description does not add any additional meaning 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/5Does 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 ('user account'), making the tool's purpose immediately obvious. It also distinguishes from sibling tools like create_user and delete_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit prerequisite ('requires WRITE_ENABLED=true'), which guides when the tool can be used. However, it does not compare to alternatives like update_record or explain scenarios where 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.
- 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 the specific categories of validation (best practices, security, performance), which provides useful 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence efficiently conveys purpose and scope with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers what the tool does, it lacks details about the output format (e.g., whether it returns a report, pass/fail, or list of issues), which would be helpful given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with adequate parameter descriptions. The tool description adds no 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Validate an artifact' with specific areas: best practices, security, and performance. This distinguishes from sibling validation tools like validate_property, 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies using this tool when needing to validate artifacts for the listed concerns, but provides no explicit guidance on when to prefer it over alternatives like validate_property or validate_query.
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 value beyond annotations by specifying the WRITE_ENABLED requirement. Annotations indicate this is a write operation (readOnlyHint=false) but not destructive, and the description 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded. It conveys essential information without extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a prerequisite but does not cover potential edge cases like duplicate addition or invalid IDs. For a simple tool with two required params and no output schema, 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for both parameters ('System ID of the user' and 'System ID of the group'). The description does not add additional meaning or examples for these 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add a user to a group'. It uses a specific verb and resource, distinguishing it from siblings like 'remove_user_from_group' and other 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a precondition: 'requires WRITE_ENABLED=true', which helps the agent understand when the tool is usable. However, it does not explicitly mention when to use this tool over alternatives or provide context for when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, etc.), the description adds that the note is 'internal' (not visible to end user) and requires WRITE_ENABLED=true, which are important behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no fluff, clearly stating the tool's purpose and a key requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with three well-described parameters and straightforward behavior, the description is mostly complete. It could optionally mention that notes are appended, but it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 add parameter details. It does not provide additional meaning beyond the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('add') and the resource ('internal work note to any ITSM record'), distinguishing it from sibling tools like 'add_comment' which likely creates external comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('requires WRITE_ENABLED=true') but does not provide guidance on when to use this tool versus alternatives like 'add_comment' or when it should not be used.
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, so the description's mention of 'close' is consistent but adds little beyond the prerequisite.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the action and includes a necessary prerequisite—no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple operation with one parameter and no output schema, the description is sufficient, though it could optionally clarify the resulting state change.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the sys_id parameter description; the tool description adds no additional parameter details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Close') and the resource ('a resolved incident'), distinguishing it from sibling tools like resolve_incident which changes state to Resolved but does not close it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for resolved incidents and requires WRITE_ENABLED=true, but does not explicitly state when not to use it or mention alternatives among 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 and openWorldHint. The description adds 'in-memory grouping', clarifying the operation does not modify the database. This provides extra 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no filler. Concise yet packs the core purpose and key behavioral trait (in-memory grouping).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 3 well-documented parameters, the description covers the essential purpose and context. Minor omission: not specifying return format or duplicate criteria, but annotations compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented. The description mentions 'specified fields' which relates to match_fields, but adds 'in-memory grouping' as behavioral context. Meets baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Find duplicate CIs by matching on specified fields', specifying the verb (Find), resource (CIs), and action (grouping duplicates). It differentiates from sibling tools like cmdb_find_orphans by focusing on duplicates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for duplicate detection but lacks explicit guidance on when to use this tool versus alternatives (e.g., cmdb_find_orphans). No when-not or context about prerequisites.
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 not read-only (readOnlyHint=false) and not idempotent (idempotentHint=false). The description adds context that the tool creates rules that auto-generate approval requests, and highlights the WRITE_ENABLED requirement. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with the main verb and resource. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 7 parameters, the description covers the core purpose, prerequisite, and a hint of behavior. It could mention the return value (e.g., sys_id of created rule) but overall sufficient for a creation tool with well-documented schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it reinforces that conditions match records and approval requests are generated, but does not elaborate on parameter formats or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create', the resource 'approval rule', and its behavior (automatically generates approval requests based on conditions). It distinguishes from many sibling tools with 'create_' prefix by specifying the exact artifact type and 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (WRITE_ENABLED=true) and the condition-based triggering, but does not explicitly state when to use this tool over alternatives like create_acl or create_business_rule. No when-not or comparison with siblings 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 the tool is not read-only and not destructive. The description adds the prerequisite for write access, but lacks other behavioral details like error handling or rate 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, one sentence with a parenthetical note. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 9 parameters and no output schema, the description is minimal but covers the essential prerequisite. Could benefit from mentioning the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 9 parameters have descriptions in the input schema (100% coverage). The description adds no additional meaning beyond what is already provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('incident record'), and includes a prerequisite. It distinguishes from siblings like close_incident and update_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear prerequisite (WRITE_ENABLED=true) but does not explicitly address when to use or when not to use relative to alternative create tools. Context is 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 destructive behavior (destructiveHint=true). The description adds a prerequisite (WRITE_ENABLED) but lacks details on error handling or idempotency implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One efficient sentence with no superfluous words, including a prerequisite condition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required param, no output schema) and annotations covering destruction, the description is largely complete, though it omits the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the parameter ('sys_id of the attachment to delete') with 100% coverage. The description adds 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete an attachment from a record' with a clear verb and resource, and includes a prerequisite. It distinguishes from sibling tools like upload_attachment or list_attachments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear condition ('requires WRITE_ENABLED=true') for using the tool, giving context but not explicitly excluding 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 cover readOnlyHint=true and openWorldHint=true, indicating safe read and dynamic results. The description adds context about the output format (JSON) and purpose (external reports), which aligns with the read-only nature. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is clear and front-loaded. It contains no unnecessary words or tautology.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 4 parameters are fully documented in the schema and annotations provide readOnly and openWorld hints, the description covers the output format and purpose. It could be more explicit about the output being a JSON array of records, but overall it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter already described (limit, query, table, fields). The description adds no new semantic information about the parameters beyond 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/5Does 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', the output format 'structured JSON', and the purpose 'for use in external reports'. It distinguishes from sibling tools like export_properties and export_update_set by specifying the data type and 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for exporting data as JSON for reports, but does not explicitly state when to use this tool over alternatives like query_records or get_record. 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?
Annotations already declare readOnlyHint=true and openWorldHint=true, indicating safe read behavior. The description adds that it searches artifacts but does not disclose additional behavioral traits like pagination or sorting. With annotations covering the safety profile, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and key criteria. No unnecessary words or repetitions. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (search with 4 params, no output schema), the description covers core functionality. It lists example artifact types. However, it omits guidance on the 'limit' parameter and return format. Still complete enough for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (3 of 4 params described). The description repeats those three (name, type, scope) without adding new meaning. The 'limit' parameter is not mentioned. With high schema coverage, baseline 3 is appropriate; the description does not exceed schema detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action 'Search' and the resource 'platform artifacts' with criteria by name, type, or scope. It distinguishes itself from sibling search tools like search_cmdb_ci or search_knowledge by focusing on platform artifacts such as business rules and scripts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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 to find artifacts by name, type, or scope. It provides search criteria but does not explicitly state when not to use it or mention alternatives. However, the criteria are 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=true and openWorldHint=true, indicating no side effects. The description adds the behavioral context that SCRIPTING_ENABLED must be true, which is critical for understanding when the tool will succeed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys the purpose and a prerequisite with no wasted words. It is 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/5Given 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 covers the functionality and a prerequisite. It could mention the return format but is sufficiently complete 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage with a clear description of the sys_id parameter. The description does not add further meaning beyond what the schema provides, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details and script body of a client script, using specific verbs and resource. It distinguishes itself from sibling tools like list_client_scripts (which lists) and update_client_script (which updates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the prerequisite SCRIPTING_ENABLED=true, providing an important condition for use. However, it does not explicitly state when to use this tool vs alternatives like list_client_scripts or update_client_script, nor does it provide 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, indicating a safe read operation. The description adds value by specifying exactly what is retrieved (SLA details and remaining time), providing context beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is 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 verb 'Get' and clearly states the resource. Every word contributes to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single parameter and no output schema, the description is reasonably complete. It conveys the key information (SLA details and remaining time) for a simple retrieval tool. Minor room for improvement: could elaborate on what 'SLA details' includes (e.g., status, start/end times).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a description for the only parameter 'case_sysid'. The tool description does not add additional 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'Get' and resource 'SLA details and remaining time for a CSM case', making the tool's purpose immediately clear. It is distinct from sibling tools like 'get_sla_details' (generic) and 'get_csm_case' (case info) by focusing on SLA 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving SLA details but provides no explicit guidance on when to use this tool over alternatives such as 'get_sla_details' or 'get_csm_case'. No exclusions or when-not-to-use information 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 readOnlyHint=true and openWorldHint=true, which indicate it is a safe read operation. The description adds no additional behavioral context beyond the action itself, such as what happens if no active update set exists or the return 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the key information. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description is mostly complete. However, it could hint at the return value (e.g., whether it returns the name, sys_id, or object). Still, it is adequate for a simple getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema provides full coverage. The description does not need to add parameter details, and the 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Get the currently active Update Set for the session'. It uses a specific verb ('Get') and resource ('currently active Update Set') and distinguishes 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this versus alternatives. The context implies it is for retrieving the current update set for the session, but it does not mention when not to use it (e.g., when needing to list all update sets or switch 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 (readOnlyHint: true, openWorldHint: true) indicate safety and flexibility. Description adds that the tool returns 'full details' including actions and trigger, which goes beyond annotations. No contradictions, but no discussion of potential performance implications or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is front-loaded with the key action and resource, effectively conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter and no output schema, the description adequately covers the tool's functionality. It mentions the key aspects (full details, actions, trigger). However, it could be slightly more complete by noting that the returned data is real-time or from cache, but this is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage for the single parameter 'name_or_sysid' with a clear description ('Flow name or sys_id'). The tool description does not add additional semantic 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/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get full details of a Flow Designer flow including its actions and trigger'. This specifies the verb (get), resource (flow), and scope (full details including actions and trigger), distinguishing it from sibling tools like list_flows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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_flows. The purpose implies it's for retrieving detailed information of a specific flow, but no when-not-to 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. The description adds 'Find' but doesn't elaborate on the openWorldHint (data from external sources) or any other behavioral traits. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that conveys the tool's purpose without any waste. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with one parameter and good annotations, the description is sufficient. It doesn't specify the return details but 'assignment group details' is adequate. No output schema, but agent can infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description covers 100% of parameters. The description repeats the schema's 'Group name or sys_id' without adding new meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Find' and the resource 'assignment group details', with the method 'by name or sys_id'. This distinguishes it from siblings like list_groups (listing) and create_group/update_group (modifications).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing details of a specific assignment group. It doesn't explicitly state when not to use or list alternatives, but context is clear given siblings. No exclusions provided.
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 mark as read-only (readOnlyHint: true) and open-world (openWorldHint: true). Description adds that it retrieves 'full content' and specifies identifier format, providing useful context beyond annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One efficient sentence with no wasted words. Perfectly concise for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter tool and no output schema, the description fully covers the purpose and input. It could optionally mention that it returns full content fields, but overall it's complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'number_or_sysid' with clear description in schema. Description adds no extra meaning beyond what the schema already provides (100% coverage), so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Describes a specific verb ('Get') and resource ('knowledge article') with a clear identifier format ('number (KB...) or sys_id'). Clearly distinguishes from siblings like 'search_knowledge' or '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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use for retrieving full article content by identifier, but lacks explicit when-to-use or when-not-to-use guidance or comparison with siblings like 'search_knowledge' or 'list_knowledge_bases'.
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 value by specifying that it returns counts (purchased, installed, in use), which provides behavioral context beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key information. No unnecessary words or repetition. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple summary tool with no output schema, the description provides enough clarity about what is returned (counts). It could optionally specify the format or structure, but it is still complete enough for an agent 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the single parameter with a clear description. The description does not add extra meaning beyond what the schema already provides. Baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'license compliance summary', and the specific data 'purchased vs. installed vs. in use counts'. It distinguishes this tool from siblings like 'list_software_licenses' (list all licenses) and 'get_license_optimization' (optimization suggestions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for compliance summaries but does not explicitly state when to use it versus alternatives like 'list_software_licenses' or 'get_license_optimization'. No guidance on when not to use it or prerequisites.
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 context about including widgets/tabs beyond the readOnlyHint annotation, but does not elaborate on what 'details' entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words, efficiently conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool, the description covers essential aspects; however, the lack of output schema and vague 'details' could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the parameter with high coverage; the description adds no additional semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves details of a PA dashboard, including its widgets/tabs, distinguishing it from list_pa_dashboards 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching a single dashboard but provides no explicit when-to-use or comparison to alternatives like list_pa_dashboards.
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 return fields (current value, target, trend direction), which is useful but minimal. It does not disclose details like aggregation behavior, period defaults, or exact response format beyond what the schema already implies. This is sufficient 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently communicates the tool's purpose and return data. No filler or redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool is a straightforward read operation with no output schema, the description adequately covers its behavior. It states what data is returned, and the schema covers the parameters. However, it could be slightly more complete by noting that it returns a summary rather than raw time series, but the current level is sufficient 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter described in the input schema. The description does not add parameter-level meaning beyond the schema, so the baseline 3 applies. No extra context about how period or include_scores affect the result is provided in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'scorecard data for a PA indicator', and enumerates the return content (current value, target, trend direction). This distinguishes it from sibling tools like get_pa_indicator or get_pa_time_series, which deal with indicator metadata or time series data respectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context of what the tool returns, which helps an agent understand when to use it (when a summary scorecard is needed). However, it does not explicitly mention alternatives or exclusions, such as 'for raw time series, use get_pa_time_series', so it lacks the explicit when-not guidance 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 provide readOnlyHint=true and openWorldHint=true, covering safety. Description adds 'Get full configuration details' which aligns but does not elaborate on behavioral traits such as return structure, auth needs, or rate limits. Minimal extra 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and resource, no wasted words. Efficiently communicates essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete enough for simple tool with 1 param and annotations. Could improve by describing what 'full configuration details' includes, but current description suffices for common use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear description for parameter 'id'. Tool description does not add additional meaning beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (Get), resource (full configuration details of a Service Portal), and identification method (by sys_id or URL suffix). Distinguishes from siblings like get_portal_page, get_portal_widget, and list_portals by specifying 'full configuration details'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for retrieving full portal configuration, but lacks explicit 'when to use' vs 'when not to use' or alternatives. No mention of sibling tools like list_portals for listing. However, the identification criteria provide clear context for invocation.
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 adds value by specifying that the layout is included in the response, providing 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that is front-loaded with the verb and object, containing no extraneous or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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, and adequate annotations), the description is sufficiently complete, covering the key aspect of returning layout details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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, and the description does not add meaning beyond what the schema 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves details of a specific Service Portal page including its layout, differentiating it from sibling tools like get_portal (portal level) and get_portal_widget (widget level).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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 such as get_portal or get_portal_widget. It implies usage for a specific page by sys_id, but lacks exclusions or alternative recommendations.
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 'full details' but does not elaborate on return format or limits. This is acceptable for a read operation but does not provide extra 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no unnecessary words. It efficiently conveys the tool's purpose and input method. Excellent structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 only says 'full details' without specifying what that includes. However, for a simple get operation on a known resource, this is generally sufficient. It could be improved by listing example fields, 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (parameter described as 'Job sys_id or exact name'). The description repeats this information ('by sys_id or name') but does not add new meaning or format details, so it provides no extra value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'scheduled job', and the method of identification ('by sys_id or name'). This distinguishes it from sibling tools like list_scheduled_jobs (which lists multiple) and create/update variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the required input (sys_id or name) and implies usage when you have an identifier. It does not explicitly mention when not to use this tool or suggest alternatives like list_scheduled_jobs, but the context is clear enough for the agent.
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 adds value by disclosing that it includes field mappings in the returned details. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 11 words, front-loaded with the action and resource. Every word is necessary and there is no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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) and annotations covering read-only behavior, the description is sufficient. It specifies what is returned (details + field mappings).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the parameter (sys_id_or_name). The description does not add any additional meaning beyond the schema's description. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets details of a Transform Map including field mappings. It uses a specific verb ('Get') and resource ('Transform Map'), distinguishing it from sibling tools like list_transform_maps (list) and list_transform_field_maps (list field maps).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when details of a specific Transform Map are needed, but it does not explicitly state when to use this tool over alternatives like list_transform_maps or run_transform_map. No when-not or exclusions are provided.
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's mention of 'tabs and lists' adds useful context without contradicting 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, 13 words, front-loaded with key information. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, describing 'details including tabs and lists' provides reasonable scope. Could be more exhaustive but sufficient for a get tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter described as 'Workspace sys_id'. 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/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get details of a configurable agent workspace including tabs and lists', specifying verb and resource. It distinguishes from siblings like list_workspaces (which lists) and other get_* 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. The name and description imply use for a single workspace, but alternatives are not 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 indicate readOnlyHint and openWorldHint. The description adds value by noting the system property requirement, but does not elaborate on other behaviors like pagination 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that efficiently conveys purpose and a key prerequisite, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 well-documented parameters, the description is mostly complete, though it could mention default ordering or pagination behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds no additional meaning beyond the schema's parameter definitions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('List business rules') and includes a critical prerequisite, clearly distinguishing it from sibling tools like get_business_rule or create_business_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite (SCRIPTING_ENABLED=true), offering implicit guidance on when this tool is usable, though it does not explicitly contrast with 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the prerequisite condition beyond the annotations (readOnlyHint=true, openWorldHint=true), which indicate the tool is read-only and non-destructive. However, it does not disclose other behavioral traits such as error handling when SCRIPTING_ENABLED is false, pagination details, or response format. The annotation already covers safety, so the description provides marginal 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that is front-loaded with the core purpose. It contains no unnecessary words or repetition, earning it a maximum score for conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with 0 required parameters and no output schema, the description is largely sufficient. It conveys the main action and a critical prerequisite. However, it could be slightly more complete by briefly noting the expected return type (e.g., an array of client script objects), but given the tool's low complexity, 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/5Does 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 (type, limit, table, active), so the schema already fully documents each parameter's meaning. The description does not add any additional context or syntax details beyond the schema, so it meets the baseline but does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists client scripts and specifies a prerequisite condition (SCRIPTING_ENABLED=true). The verb 'List' and resource 'client scripts' match the tool name and distinguish it from sibling tools like get_client_script or 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage guideline by stating the requirement 'requires SCRIPTING_ENABLED=true', helping the agent know when to use this tool. However, it does not explicitly mention when not to use it or compare with alternative listing tools, though the tool name and context are sufficient for differentiation.
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 and openWorld hints. The description adds contextual value by specifying 'multi-instance / multi-customer support', which clarifies the scope beyond the annotations. No contradictions, and additional traits (like listing all configured instances) 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that immediately conveys the tool's purpose. Every word is functional; there is no fluff. It is appropriately concise for a parameterless read-only tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, annotations, and no output schema, the description is complete enough for an agent to understand the action and scope. However, it could potentially clarify that the return is a list of instance identifiers or details, but this is not a critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description does not need to elaborate on parameter semantics. Schema coverage is 100%, and the description adds no redundant information. 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/5Does 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 ('all configured ServiceNow instances'). It distinguishes from sibling tools like 'list_users' or 'list_reports' by specifying the domain of instances and multi-instance/multi-customer support.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 other list tools (e.g., when to list instances vs. list users). No alternatives or exclusions are mentioned, leaving the agent without clear 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.
- 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 variability. The description adds the 'requires NOW_ASSIST_ENABLED' prerequisite, which is useful context beyond annotations. No further behavioral traits (e.g., pagination, ordering) 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no superfluous words. The key information (action, resource, prerequisite) is front-loaded. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool is a simple list operation with readOnlyHint and openWorldHint, the description adequately covers the purpose and a key prerequisite. However, it could mention the default limit or that it returns definitions, and it doesn't address the output format since no output schema is provided. Overall, sufficient 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters (limit, query, active). The description does not add any additional parameter 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action 'List' and the resource 'Now Assist skill definitions'. The prerequisite 'requires NOW_ASSIST_ENABLED' adds specificity. It distinguishes from sibling 'get_now_assist_skill' which retrieves a single skill.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a clear prerequisite (NOW_ASSIST_ENABLED), which guides when the tool can be used. However, it does not explicitly mention when to use this tool over alternatives like 'get_now_assist_skill' or other list tools, though the name implies listing multiple definitions.
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, so description does not need to restate safety or scope. Description adds behavioral context (performance metrics). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, highly efficient, front-loaded with purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two optional parameters, the description adequately conveys purpose and metrics. However, lacking output schema or return type hints, it could slightly improve by indicating the nature of the analysis (e.g., summary stats). Still, good overall.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions for days and topic_sys_id. The tool description adds no additional parameter semantics beyond what schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool analyzes Virtual Agent NLU performance, specifying metrics like conversation completion rates and fallback metrics. It distinguishes from sibling tools such as get_va_topic by focusing on performance analysis rather than retrieving individual 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied (for analyzing NLU performance), but no explicit guidance on when to use this tool versus alternatives like get_va_conversation or list_va_conversations. Lacks when-not-to-use 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 destructiveHint=true, and the description adds a behavioral constraint (WRITE_ENABLED requirement). 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and directly states the core purpose and a key requirement. It wastes no words, though it could include a bit more context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-param tool with full schema coverage, the description is minimally sufficient. It lacks details on post-rejection effects or return values, but the tool is straightforward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. The description adds no additional meaning about the parameters beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'reject' and identifies the resource as 'pending approval request', which clearly distinguishes it from siblings like 'approve_request' and '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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions a prerequisite ('requires WRITE_ENABLED=true') and the verb implies when to use (to reject). However, it does not explicitly contrast with alternative tools like 'approve_request'.
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 non-destructive, idempotent write operation. The description adds the environment prerequisite, which is valuable behavioral context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is direct and includes the essential prerequisite. No unnecessary words; highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with annotations present, the description includes a key precondition. It does not explain return values or error cases, but given the simplicity and lack of output schema, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes both parameters. The description does not add any additional meaning or context beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Update' and the resource 'business rule'. The prerequisite distinguishes it from create and get tools among siblings, 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions a prerequisite (SCRIPTING_ENABLED=true) which provides some guidance on when the tool can be used, but does not explicitly compare to 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context about the WRITE_ENABLED requirement, which is beyond annotations. Consistent with idempotentHint=true, no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence conveying purpose and requirement with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose and a key prerequisite, but lacks details on response or side effects. Acceptable for a simple update tool with idempotent hint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both fields and sys_id. Description does not add additional parameter meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states action 'Update' and resource 'PA dashboard', with a specific requirement. Distinguishes from siblings like create_dashboard or get_pa_dashboard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions required setting 'WRITE_ENABLED=true' but does not provide when-to-use versus alternatives or when not 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive. Description adds context that it updates source code, but no further behavioral details beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 10 words, front-loaded with purpose and requirement. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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. Lacks details on behavior for partial updates or error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions. Description repeats some parameter info ('template, css, client_script...') but adds no extra meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Update an existing Service Portal widget's source code' with a specific verb and resource. It distinguishes from sibling tools like create_portal_widget and get_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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states a precondition (WRITE_ENABLED=true). Does not mention alternatives or when not to use, but the constraint is clear for a mutation 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 cover idempotency and non-destructive nature. The description adds a behavioral constraint (WRITE_ENABLED=true) that is not in annotations, providing useful context beyond the structured fields. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no waste. Every word adds value, specifying the action, resource, and a key condition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool, with annotations covering safety and idempotency, and schema fully describing parameters, the description is adequate. It lacks details on return format or error handling, but these are not critical for this use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions. The description does not add extra meaning beyond what is in the schema (e.g., 'key-value pairs' is already present). Baseline score 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb ('update') and the resource ('existing problem'), clearly distinguishing it from create_problem or resolve_problem. It also notes a prerequisite (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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite (WRITE_ENABLED=true), which helps in deciding when to use the tool. However, it does not explicitly discuss when not to use it or compare it to similar sibling tools like update_record or update_incident, leaving the agent to infer context from the 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 indicate write (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds the 'WRITE_ENABLED=true' requirement, which is a useful behavioral constraint not captured in annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the purpose. It is concise and clear, though it could be slightly expanded to include the idempotent or partial update nature without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters and no output schema, the description is adequate but minimal. It covers the core purpose and a key prerequisite, but does not address validation, side effects, or what the tool returns. Sibling tools are not referenced for contrast.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters, so the baseline is 3. The description does not explain the parameters beyond what the schema provides (e.g., 'fields' is an object of updatable fields). No additional semantics added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing scoped application', using a specific verb and resource. This distinguishes it from sibling tools like create_scoped_app (creation) and get_scoped_app (read). 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a clear prerequisite ('requires WRITE_ENABLED=true'), which helps the agent know when the tool can be used. However, it does not explicitly contrast with alternatives like create_scoped_app for new apps, though that is implied by the name and 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 indicate this is a mutable, idempotent, non-destructive operation. The description adds behavioral context by specifying the SCRIPTING_ENABLED prerequisite, which is a critical constraint not covered by annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is 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 action and includes a 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and simple parameters, the description is fairly complete. It states the operation and a required setting. However, it could mention that fields is a key-value object for script attributes, but the schema already covers that. The annotations provide a safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, describing both parameters adequately. The description does not add further meaning or examples 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('script include'), clearly stating the action. It distinguishes from sibling tools like create_script_include, get_script_include, and list_script_includes by focusing on modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('requires SCRIPTING_ENABLED=true'), which is useful for context. However, it does not explicitly state when to use this tool over alternatives like update_record, nor does it provide guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/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 scripting requirement as behavioral context, but does not elaborate on side effects or other traits. It adds one piece of 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action, and contains no unnecessary words. It is highly concise and structured efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with two parameters and no output schema, the description is sufficiently complete. It includes a key requirement but could mention that the update is an in-place modification of the specific UI Action identified by sys_id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description does not add any meaning beyond what the schema already provides (sys_id and fields). No parameter semantics are elaborated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing UI Action', which is specific and uses a verb+resource structure. It distinguishes from siblings like create_ui_action, get_ui_action, and list_ui_actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a prerequisite ('requires SCRIPTING_ENABLED=true'), providing context for when the tool can be used. However, it does not explicitly exclude alternatives or specify when not to use it, but the requirement is a useful 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 declare readOnlyHint=true and openWorldHint=true, so the description's statement 'check for conflicts and missing dependencies' adds context about the checking behavior but no contradiction. It doesn't elaborate on other behavioral traits like permissions 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately conveys the core functionality. It is concise, front-loaded, and contains no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two optional parameters, annotations present, and no output schema, the description covers the main purpose and inputs. It could optionally mention the format of validation results, but the description is adequate for the 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the description adds context by linking parameters to 'app' and 'update set' and explaining the validation purpose. This is sufficient but does not provide additional constraints or format details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Pre-validate an update set or app before deployment — check for conflicts and missing dependencies'. It uses a specific verb ('pre-validate') and resource ('update set or app'), and distinguishes itself from sibling validation tools like validate_artifact, validate_property, and validate_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use the tool ('before deployment') and mentions the two alternative inputs. However, it does not explicitly state when not to use it or list alternative tools for other validation contexts, though the sibling list suggests differentiation.
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-read-only, non-destructive action. The description adds a behavioral condition (WRITE_ENABLED=true) but does not detail side effects (e.g., record state changes, notifications).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous words. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 omits details on what happens after approval (e.g., record state change, email notifications). Sufficient but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no extra meaning beyond the schema definitions for sys_id and comments. Baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('approve'), the resource ('pending approval request'), and a prerequisite ('WRITE_ENABLED=true'). It is specific and distinguishes from siblings like reject_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies a prerequisite (WRITE_ENABLED=true) and implies use for approving requests, but does not explicitly contrast with alternatives like reject_request or submit_change_for_approval.
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 permission requirement beyond annotations, and explains the conceptual behavior. Annotations already indicate non-readonly and non-destructive, so no contradiction. Could mention side effects or error states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that efficiently convey action, prerequisite, and purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about the return value or outcome, and does not mention validation or error scenarios. Without an output schema, this is a gap. However, annotations and schema cover many aspects adequately for a create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a description. The description provides high-level context but does not add significant per-parameter meaning beyond the schema. 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a PA breakdown, specifies the target table, and explains what breakdowns do (slice an indicator by dimension). This distinguishes it from other create_ tools like create_pa_indicator.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes a prerequisite (WRITE_ENABLED=true) and an example of slicing by dimension. However, it does not explicitly state when to use this tool versus alternatives like update_pa_breakdown or list_pa_breakdowns.
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 value by specifying the required permission 'WRITE_ENABLED=true', which is not in annotations. It does not mention behavior on duplicate names or what happens if the widget already exists, but overall adds useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is completely free of fluff. It front-loads the main purpose and includes a crucial prerequisite in parentheses. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, a write operation, no output schema, and annotations providing basic hints, the description is somewhat minimal. It does not explain the return value (likely the created widget's sys_id) or failure scenarios. For a create tool, the behavior is standard, but more detail on expected outcome or error conditions would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 8 parameters. The description mentions 'template, CSS, and scripts' which maps to some parameters but does not add meaning beyond the schema. Baseline is 3 due to high schema coverage, and 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/5Does 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 'Service Portal widget', and lists key components (template, CSS, scripts). It distinguishes from sibling tools like update_portal_widget and create_portal_page by the specific resource type and action. The inclusion of a prerequisite (requires WRITE_ENABLED=true) adds 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a required permission (WRITE_ENABLED=true), providing a usage condition. However, it does not explicitly state when to use this tool vs. alternatives (e.g., update_portal_widget) or when not to use it. The context of 'Create' implies new widget creation, but could be more direct about 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 provide readOnlyHint and openWorldHint. Description adds caching behavior (30 minutes), but does not disclose prerequisites (e.g., table must exist) or what happens on error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with the primary action and outcome. Each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 explain what the tool returns (e.g., schema details, success message). It mentions caching but not return value. For a discovery tool, this is a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes both parameters with 100% coverage. Description adds context that a subset of operations can be specified, but this is implied by the schema's enum. No additional syntax or format details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it discovers a ServiceNow table schema and registers dynamic CRUD tools. It lists the specific tools that become available and distinguishes itself from all sibling CRUD tools which are static and table-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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description clearly implies usage for dynamically creating CRUD tools for any table, but does not explicitly state when not to use it or mention alternatives like the static table-specific tools in the sibling 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?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds that the operation is read-only and only works on ServiceNow docs, providing marginal extra context beyond the annotations. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three short sentences, each delivering essential information: purpose, inputs, usage context. No wasted words; well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool, good annotations, and full schema coverage, the description covers all needed aspects: what it does, how to call, when to use, and constraints (read-only, Servicenow docs only). It is complete for a straightforward fetch operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description adds preference guidance (ref preferred over URL) but does not add significant meaning beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches full readable text of a ServiceNow documentation page, specifies input options (ref or URL), and distinguishes it from the sibling search tool search_servicenow_docs by indicating the full text retrieval 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends using the tool after search_servicenow_docs to read results in full, and notes that ref is preferred over URL. It provides clear guidance on when and how to use the tool, though it does not explicitly list situations 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 provide readOnlyHint=true; description adds specific detail about retrieving script body and required setting, enhancing beyond annotations without 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with purpose, resource, and prerequisite front-loaded. No unnecessary words; very efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for simple get operation but lacks details about return format or fields beyond script body. Without output schema, more clarity needed for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers sys_id with description 'System ID of the business rule' (100% coverage). Description does not add extra meaning, meeting baseline but not exceeding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get full details and script body' as verb+resource, distinguishes from siblings like list_business_rules (summary) and update_business_rule (modification). Includes prerequisite for 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes what is retrieved and prerequisite (SCRIPTING_ENABLED=true), but does not contrast with list_business_rules or other get tools for alternative scenarios. Still clear enough 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 readOnlyHint=true and openWorldHint=true. The description adds that the tool lists 'available' solutions and specifies content as 'classification/similarity models', providing useful context about the dynamic nature of results. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence of 10 words that front-loads the action 'List' and includes no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description is largely sufficient. It could be improved by hinting at the return structure (e.g., names or IDs), but the annotations and empty schema make this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there is no need for parameter descriptions. The description fully covers what the tool does with no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List available Predictive Intelligence solutions (classification/similarity models)' clearly states the verb 'List' and the resource 'Predictive Intelligence solutions', specifying the types. It effectively distinguishes this tool from sibling list tools by focusing on PI models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 ml_similar_incidents or other ML tools. It lacks any context about prerequisites or exclusion 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 indicate read-only and open-world. Description adds specifics about returned metrics and the optional days parameter. No contradictions. Describes behavior beyond annotations by listing the dashboard components.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence efficiently conveys purpose and key metrics without extraneous information. Front-loaded with core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description must explain return content. It does so adequately: open incidents by severity, vulnerability counts, mean time to resolve. For a dashboard tool with one optional parameter, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter. Description mentions the 'days' parameter but does not add new meaning beyond the schema's description. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves a security posture dashboard with specific metrics (open incidents by severity, vulnerability counts, mean time to resolve). This verb+resource combination distinguishes it from sibling tools like 'get_security_incident' or 'get_vulnerability' which return single 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the dashboard nature and sibling names, but no explicit 'when to use' or 'alternatives' guidance is provided. Agent must infer that this is for aggregate overview rather than individual records.
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 description adds context about returning resolved incidents ranked by keyword match count. It does not elaborate on potential edge cases (e.g., both parameters provided) but adds moderate 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences that front-load the purpose and immediately convey usage. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description provides essential info: returns resolved incidents ranked by keyword match count. Lacks details on output format (e.g., list of sys_ids or full records), but sufficient for a read-only search tool. Could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description clarifies the mutual exclusivity of incident_sys_id and short_description, and mentions that limit controls max results. This adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds similar past incidents using keyword-based matching, with two distinct modes (by incident sys_id or by short_description). This differentiates it from sibling tools like get_incident or ml_auto_categorize.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to provide either an incident_sys_id or a short_description, indicating mutual exclusivity. It states the output is resolved incidents ranked by keyword match count. While it doesn't mention alternatives or when not to use, 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.
- 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), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds the requirement SCRIPTING_ENABLED=true, which is valuable context. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with a parenthetical prerequisite. Every word is necessary and adds value. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While annotations and schema cover the basics, the description lacks information about the return value or success behavior. Also, no details about required permissions beyond SCRIPTING_ENABLED. For a moderate complexity tool with no output schema, this is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description enriches the 'fields' parameter by giving examples ('script, active, name, type, etc.'), which helps the agent understand what can be updated. 'sys_id' description is clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Update an existing client script' with a specific resource and verb. It distinguishes well from sibling tools like create_client_script (creation) and get_client_script (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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a prerequisite ('requires SCRIPTING_ENABLED=true') but lacks explicit guidance on when to use this tool versus alternatives like update_record. It does not provide exclusion criteria or specific use 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?
The description adds the important behavioral context that write permissions are needed, which is not provided by the annotations. It does not contradict the existing annotations (readOnlyHint=false, idempotentHint=true, etc.).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the core purpose and a key requirement without any wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple update tool with high schema coverage and clear annotations. However, it does not mention return values or potential side effects, and given the complexity of incident updates, a bit more context could be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters with 100% coverage. The description does not add any additional meaning or examples beyond what is 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update fields') and the resource ('existing incident'), with a specific verb and resource that distinguishes it from siblings like 'resolve_incident' or 'close_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/5Does 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'), guiding when the tool can be used. It does not explicitly state alternatives or when not to use it, but the context is sufficient for typical use 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 (readOnlyHint=false, idempotentHint=false) already indicate mutation. The description adds context about required configuration (WRITE_ENABLED=true), but does not discuss failure behaviors (e.g., duplicate file names, missing records) or size 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action. Every word adds value. No unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so return values are not explained. Could address file size limits, encoding specifics (though schema says 'standard base64'), and error handling. Sufficient for a simple upload tool but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 5 parameters. The description reinforces base64 encoding and provides examples, but adds no substantive 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'upload' and resource 'base64-encoded attachment to a ServiceNow record', with explicit prerequisites and usage examples. It distinguishes from sibling tools like delete_attachment or 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the 'WRITE_ENABLED=true' prerequisite and provides typical use cases ('adding files, screenshots, or documents to incidents, changes, etc.'), but does not explicitly exclude 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. Description adds specific requirement (WRITE_ENABLED=true) and mentions closure with codes and notes, aligning with destructive nature. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundancy. Directly conveys action, required parameters, and precondition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers action, required inputs, and a key precondition. Lacks information about return value or state change, but given simplicity and no output schema, it is nearly complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are fully documented in the schema (100% coverage). Description merely restates 'close code and notes' without adding semantic context beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states action (close), resource (change request), required parameters (close code and notes), and a prerequisite (WRITE_ENABLED=true). Distinguishes from siblings like 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a prerequisite for use (WRITE_ENABLED=true). Implicitly distinguishes from update and approval tools, but does not explicitly state when not to use or list 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 and openWorldHint, so the description carries less burden. It doesn't add behavioral details beyond what the annotations provide, which is acceptable but not additive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states the core functionality, second provides a use case. No wasted words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of comparing instances and the lack of an output schema, the description adequately explains the tool's purpose and parameters. It could mention the return format, but the information provided is sufficient for selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaning by explaining the optional use of 'query' with 'table' for record counts and 'property' for property comparison. This clarifies the intended parameter combinations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares two ServiceNow instances on record counts and system property values, and explicitly mentions its use case for dev→prod drift detection. This distinguishes it from siblings like 'compare_record_counts' by adding property comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case ('drift detection and governance'), implying when to use it. While it doesn't explicitly state when not to use or list alternatives, the context is sufficient for an AI 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 indicate a non-read-only, non-idempotent, non-destructive write operation. Description adds context about auto-generated ACLs and prerequisites, complementing annotations without 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with clear verb, resource, and constraints. Front-loaded and efficient, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given annotations and full schema coverage, the description is sufficient for a creation tool. It mentions prerequisites and optional behavior, though could detail response or restrictions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents parameters. Description adds only the auto-generate ACLs hint, providing marginal benefit beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool creates an AI agent definition, with optional ACL auto-generation. It includes prerequisites (NOW_ASSIST_ENABLED + WRITE_ENABLED) and distinguishes from sibling tools like create_agentic_workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions required features (NOW_ASSIST_ENABLED, WRITE_ENABLED), guiding when the tool can be used. Does not explicitly list alternatives but the sibling context makes 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 disclose the non-read-only, non-idempotent, non-destructive nature. The description adds the scripting-enabled requirement, which is useful operational context beyond what annotations provide. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and a concise prerequisite in parentheses. It contains no filler or redundancy, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema and annotations, the description is mostly sufficient for a simple create operation. However, since there is no output schema, a brief mention of the return format or failure behavior would have been beneficial. 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds no additional parameter-specific meaning beyond the schema, which is acceptable given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new script include' uses a specific verb and resource, clearly distinguishing this from siblings like get_script_include, update_script_include, and list_script_includes. The added prerequisite '(requires SCRIPTING_ENABLED=true)' further clarifies 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite (SCRIPTING_ENABLED=true) that an agent needs to know before invoking the tool. While it doesn't explicitly name alternatives, the action is unambiguous and the prerequisite gives solid 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 provide destructiveHint=true and readOnlyHint=false. The description adds value by disclosing the WRITE_ENABLED prerequisite and the dry_run preview behavior, which exceeds 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with main action and prerequisite, then dry_run detail. Ideal length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description covers the core action, prerequisite, and dry_run. For a delete tool, this is largely sufficient, though it could mention success/error behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description adds minimal additional meaning beyond highlighting the dry_run option and the 32-character sys_id requirement, which is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a record from any ServiceNow table, distinguishing it from sibling tools like 'delete_attachment' or 'delete_system_property' that target specific tables. The verb 'delete' and resource 'record from any ServiceNow table' are 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions the prerequisite (WRITE_ENABLED=true) and the dry_run option for preview. It implies when to use (when needing to delete a record from any table) but does not explicitly contrast with alternatives like 'delete_attachment'.
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=true and openWorldHint=true annotations already present, the description adds value by disclosing the fuzzy nature of results: 'Matches are substring (LIKE) hits — candidates to review, not definitive.' This honestly frames the output as needing review, which is valuable 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, zero filler. Each sentence earns its place: purpose, when-to-use, and caveat about result type. Front-loaded with the core function first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with good annotations, full schema coverage, and no output schema, the description is adequate. It explains the fuzzy matching nature, the review workflow, and the use case. Could optionally mention the sources searched (e.g., which script tables), but this is a minor gap for a candidate-screening tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters well-described in the schema (name with an example, limit with default). The description doesn't add much beyond schema for parameters, but the 'name' example is in the schema. Description adds slight value by reiterating the substring matching semantics. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource+scope: 'find scripts that read a system property by name, plus the property record itself.' It specifies what is searched (scripts, system properties), the match mechanism (substring LIKE), and the result scope (candidates plus the property record). Distinguishes from siblings like get_system_property (returns one property) and search_system_properties (returns property matches only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use it before changing or removing a property.' This is clear context. It does not explicitly name alternative tools for when you only need the property itself or the property value list, but the timing guidance (before mutation) is well-defined.
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 the tool as read-only and open-world. The description adds that it returns an upgrade hint when out of date, which provides 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loading the main function and adding a key behavioral detail. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose and return value (version check, upgrade hint) adequately. Without an output schema, it could be slightly more explicit about the exact return format, but it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the description cannot add meaning beyond the schema. A baseline of 4 is appropriate as no parameter information is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reports the SDK version and checks against a tracked version (4.8.0), with an upgrade hint. This distinguishes it from siblings like fluent_build, fluent_explain, etc., 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking SDK version compatibility but provides no explicit when-to-use or alternative guidance. However, the unique purpose is clear 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. The description adds that it returns 'full details,' which implies a comprehensive response but does not elaborate on specific fields or format. This is adequate but does not significantly enhance 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy. Every word serves a purpose, efficiently conveying the tool's function and parameter format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, read-only), the description is nearly complete. It does not specify the return structure, but 'full details' adequately conveys the output. Adding a note about the response containing the entire case record would be a minor improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with a description for the single parameter. The description adds examples (e.g., CS0001234) that clarify the expected format, providing value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves full details of a CSM case using either a case number or sys_id. It explicitly references the resource (CSM case) and identification methods, distinguishing it from siblings like get_csm_account or get_csm_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly advises when to use the tool (when full case details are needed by number or sys_id). While it doesn't explicitly list when not to use it or provide alternatives, the context of sibling tools like get_csm_case_sla and close_csm_case makes the usage 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 provide readOnlyHint and openWorldHint. The description adds the prerequisite NOW_ASSIST_ENABLED, which is useful beyond annotations. It does not detail error behavior or return structure, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action, and includes a relevant prerequisite in parentheses. No unnecessary words; efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 annotations, the description covers purpose and a prerequisite. It lacks details about the return structure or where to find sys_id, but is mostly complete 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with sys_id described as 'System ID of the skill'. The description adds 'by sys_id' but no additional semantic meaning. Baseline 3 is appropriate as 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single Now Assist skill definition by sys_id', specifying the verb and resource uniquely. It distinguishes from sibling tools like list_now_assist_skills (listing) and create_now_assist_skill (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/5Does 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 and need a skill definition, and mentions the prerequisite 'requires NOW_ASSIST_ENABLED'. However, it lacks explicit guidance on when not to use it (e.g., for listing) or alternatives, though context from siblings helps.
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; description adds the important prerequisite SCRIPTING_ENABLED=true. No contradiction. Could mention that it returns the full script field, but not necessary given the purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the action and resource. No wasted words; every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with good annotations and single parameter, the description is adequate. Lacks mention of error handling or behavior when script include not found, but overall sufficient 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the parameter with 100% description coverage (sys_id_or_name). Description does not add additional semantics beyond 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/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get full script body of a script include' with specific verb and resource. It distinguishes from sibling tools like list_script_includes (lists metadata) and execute_script (runs 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states prerequisite 'requires SCRIPTING_ENABLED=true'. Does not mention when to use vs alternatives like get_record or execute_script, but the purpose is clear enough for an agent to infer.
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 requirement of SCRIPTING_ENABLED=true beyond annotations, which indicates a conditional access. Annotations already mark it as read-only and open world, so the description provides useful 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the key action and requirement. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with one parameter, the description is adequate. It mentions the return includes 'full details and script', which implies the return value. No output schema exists, but the description covers the essential context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the single parameter with a description. The tool description does not add additional meaning 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/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly describes the action as getting full details and script of a UI Action, differentiating from listing operations. The verb 'get' and resource 'UI Action' 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
States a prerequisite (SCRIPTING_ENABLED=true) that guides usage. Does not explicitly mention alternatives like list_ui_actions, but the context hints at 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 mark readOnlyHint=true and openWorldHint=true. The description adds the crucial prerequisite 'requires SCRIPTING_ENABLED=true', providing behavioral context beyond the annotations. No contradiction 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, minimal and efficient. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one required parameter and no output schema, the description adequately explains the scope ('full details and conditions'). Some might expect mention of the response format, but it's sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter 'sys_id' with a description. The description doesn't add further meaning, but 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details and conditions of a UI Policy. The verb 'Get' and specific resource 'UI Policy' make the purpose unambiguous, distinguishing it from list_ui_policies among 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the prerequisite requirement SCRIPTING_ENABLED=true, guiding the agent on when to use. While it doesn't list alternatives or when not to use, the constraint is clear and actionable.
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 no readOnly, no idempotency, no destructiveness. The description adds behavioral context: the tool exports to XML and requires a configuration flag, which is valuable beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys purpose and prerequisite without extraneous 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, single-parameter tool with clear purpose and prerequisites, the description is mostly complete. It could mention what happens with the XML output (e.g., returned or saved), but the current info suffices for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description does not add meaning beyond the schema for the single parameter 'sys_id'. Baseline score applies as description adds no parameter-specific insights.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Publish/export', the resource 'update set', the output format 'XML', and a prerequisite condition. It distinguishes from siblings like commit_changeset and export_update_set by specifying 'for 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (SCRIPTING_ENABLED=true) but does not explicitly state when to use this tool versus alternatives like commit_changeset or preview_update_set. The purpose for deployment provides context, but exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the requirement 'requires WRITE_ENABLED=true', which goes beyond the annotations (destructiveHint: true). It does not contradict annotations and provides 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that effectively communicates the tool's purpose and a key constraint without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 provides the core purpose and a constraint. It could be slightly more complete by explaining that the member_sys_id implies the group, but overall it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a description for the single parameter 'member_sys_id'. The tool description does not add 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Remove a user from a group' and includes a necessary requirement. It is distinct from the sibling tool 'add_user_to_group', which performs the opposite 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to remove a user from a group) but does not explicitly state when not to use it or provide alternatives. The sibling list helps differentiate, but the description itself 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?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds behavioral value by explaining the 'no local copy to compare' concept and the field-state reporting format. It doesn't mention error behavior, permission requirements, or pagination, but for a read-only diff tool the annotations carry much of 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both information-dense. The first sentence establishes the comparison semantics and output states; the second explains the sys_updated_on return value and its downstream use. Zero filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a comparison tool with 100% schema coverage and readOnly/openWorld annotations, the description covers the key aspects: what it compares, default comparison source, output state enum, and how the result informs a sibling tool. Slightly short on the return structure detail beyond field states and sys_updated_on, but adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for all three parameters, providing descriptions for table, sys_id, and fields. The description adds significant value by explaining the 'fields' parameter semantics (defaults to files under NOWAIKIT_SYNC_DIR) and clarifying that sys_id accepts a name as an alternative. This goes beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('compare'), a specific resource ('artifact's current instance content'), and a precise scope ('field-by-field'). It also names the output states (unchanged | changed | not_local), distinguishing it clearly from sibling tools like push_artifact and pull_artifact. 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates this is a read-only comparison used as a precursor to push_artifact, explicitly noting it returns data 'to feed into push_artifact's conflict check'. This gives useful context, though it doesn't explicitly state when NOT to use it or name direct 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 show readOnlyHint=false and destructiveHint=false. The description adds that WRITE_ENABLED=true is required, providing behavioral context beyond annotations. It does not detail side effects, but for a simple trigger action 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the main action and includes the prerequisite. Every word adds value; no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no output schema), the description is sufficient. It explains what the tool does and a key requirement. It does not explain return values but that is often assumed for such actions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'sys_id' described as 'Scheduled job sys_id to trigger'. The description does not add additional meaning beyond the schema, but it is consistent and clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Immediately execute a scheduled job on-demand', specifying the verb 'execute' and resource 'scheduled job'. It distinguishes from siblings like 'get_scheduled_job' or 'update_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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use (on-demand) and includes a prerequisite (WRITE_ENABLED=true). It does not explicitly mention alternatives, but context from sibling tools makes the purpose 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 mutation (readOnlyHint=false) and safety (destructiveHint=false). Description adds the behavioral requirement of scripting enabled, which is not in annotations. No contradictions. Could elaborate on side effects, but sufficient given 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence efficiently conveys core action and prerequisite. No unnecessary words. Front-loaded with verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update tool with 2 parameters and no output schema, the description provides the essential prerequisite. It could mention that the operation is idempotent (matching annotation) or what is returned, but the simple nature makes it adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with descriptions for both sys_id and fields. Description does not add new semantic details beyond what schema provides. Baseline score of 3 is appropriate as the description adds no extra meaning for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'Update' and the resource 'existing ACL rule'. Distinguishes from siblings like create_acl and list_acls by specifying it modifies an existing rule. Includes a critical prerequisite (SCRIPTING_ENABLED=true) that 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit prerequisite (SCRIPTING_ENABLED=true), guiding agents on when this tool is usable. However, does not compare against alternatives like patch operations or explain when not to use it (e.g., for new ACLs). Still, the precondition is valuable 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?
The description adds the WRITE_ENABLED requirement beyond annotations. Annotations already indicate non-read-only and non-destructive, and the description confirms mutation. It does not contradict annotations and 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, followed by the precondition in parentheses. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with no output schema, the description provides enough context: what it does and a key prerequisite. The sibling list is large but the description is sufficiently specific to HR cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have descriptions in the schema (100% coverage), so the tool description adds no new semantic meaning. The description mentions 'fields' generically but does not enhance schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update fields' and the resource 'an existing HR case', and adds a precondition 'requires WRITE_ENABLED=true'. It distinguishes this tool from siblings like 'close_hr_case' and 'create_hr_case'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a precondition (WRITE_ENABLED=true) which gives context for use. While it does not explicitly list when to use vs alternatives, the purpose is clear enough for an agent to decide. It lacks explicit exclusions but provides adequate 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 indicate it's a write operation (readOnlyHint=false) and idempotent (idempotentHint=true). The description adds the specific requirement 'WRITE_ENABLED=true', providing additional 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the purpose, containing no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with 2 parameters and no output schema, the description covers the essential purpose and a key requirement, making it adequate if not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters described in the schema. The description does not add 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/5Does 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 'HR profile fields for a user', and distinguishes from the sibling 'get_hr_profile' which is read-only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a prerequisite ('requires WRITE_ENABLED=true') which guides when to use the tool, but does not explicitly state when not to use it or mention alternatives like get_hr_profile for reading.
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 explicitly states 'Read-only', and annotations already provide readOnlyHint=true and openWorldHint=true, so there is no contradiction (which would have been a 1). The description adds value by listing the return artifact types (chart-ready series, Teams Adaptive Card, markdown table, summary) and confirming real-time behavior, which goes beyond what annotations offer. It doesn't disclose rate limits or scale constraints, but for a read-only visualization with strong annotation coverage 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured block of two sentences, front-loading the core purpose before listing output formats. Every clause contributes value—the purpose, the example, the output list, and the read-only assurance. Zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description helpfully enumerates what the tool returns (chart-ready series, Teams Adaptive Card, markdown table, summary), which compensates for the missing structured return info. The schema covers all parameters at 100%. However, for a 'real-time' visualization tool it doesn't clarify pagination, how many data points are returned per interval, or limits on the date range, leaving minor gaps for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are documented in the schema itself, which sets a baseline of 3. The description adds marginal value with the query span-filter example ('ONLast 30 days') and reinforces the default for interval/day/date_field in the schema. However, it does not add semantic meaning beyond the schema's parameter descriptions, so it does not exceed baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Build') with a clear resource ('a real-time trend line of ServiceNow record counts over time') and even gives an example ('incidents opened per day'). It also enumerates the chart-ready output formats (series, Teams Adaptive Card, markdown table, summary), which strongly distinguishes it from visually similar siblings like visualize_aggregate and trend_query. It further asserts read-only status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for use (counting records over time) with a concrete example, and the query parameter guidance ('Recommended: a span filter... e.g. ONLast 30 days') adds practical usage direction. However, it does not explicitly state when NOT to use this tool or name alternatives (e.g., when to prefer visualize_aggregate or trend_query instead), so it stops short of a full 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 context beyond annotations: requires write permission, dry_run preview. No contradiction with annotations (readOnlyHint=false, etc.). Does not describe return format, but annotations already indicate mutability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and prerequisite, no fluff. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing return value description (e.g., sys_id of created record). Dry_run behavior partially addressed. With no output schema, description should clarify return but falls short.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds scope to table parameter ('any ServiceNow table') and dry_run behavior. Fields parameter not enriched beyond schema, but overall adds value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb ('Create'), resource ('new record in any ServiceNow table'), and prerequisite (WRITE_ENABLED=true). Distinguishes from siblings (e.g., specific create_incident) 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides prerequisite (WRITE_ENABLED=true) and a use case (dry_run preview). Does not explicitly contrast with specific create tools but implicitly guides toward general table 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 indicate readOnlyHint=true and openWorldHint=true. The description adds the prerequisite and clarifies that it retrieves script and role details, providing useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is clear, front-loaded, and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with no output schema, the description adequately explains what is returned (full details, script, role) and the prerequisite, making it complete for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage and only one parameter (sys_id), the description adds no additional meaning beyond the schema's 'ACL sys_id'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 ACL rule, specifically mentioning script and role requirements. It includes a prerequisite, distinguishing it from list_acls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a requirement (SCRIPTING_ENABLED=true) but does not explicitly contrast with sibling list_acls or specify when to use this tool over 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 and openWorldHint. The description adds value by specifying the return values (name and URL), which is not covered by annotations. No behavioral contradictions are noted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys all necessary information without 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no output schema, and the simple nature of the tool, the description is complete. It clearly states what the tool does and what it returns, leaving no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description does not need to add meaning beyond the schema. The schema is fully covered (100%). Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'currently active ServiceNow instance', and the output 'name and URL'. It distinguishes from sibling tools like get_record or get_incident which retrieve specific objects, while this retrieves instance-level information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates it is for obtaining the active instance context, but it does not explicitly state when to use this tool versus alternatives like switch_instance or list_instances. No exclusions or specific context are provided.
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, indicating a safe read with possibly unbounded results. The description adds that it returns record counts per category, which is a behavioral trait not inferable from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that conveys the tool's purpose and output without any superfluous words. It is 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains that the tool returns unique categories and their record counts. There are no required inputs or complex behaviors to document, making the description complete for this simple listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100% (empty). The description adds no parameter details because none exist, but it does explain what the output contains. Baseline 4 is appropriate for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists unique property categories with their record counts. It uses a specific verb ('list') and specific resource ('property categories') with an explicit output scope, distinguishing it from other list tools that list properties or system properties directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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 like list_system_properties or list_va_categories. The description implies it's for category-level aggregation, but lacks when-to-use or when-not-to-use instructions given the many similar list 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, so the read-only nature is covered. The description adds context about the return shape ('{count, records} or {error}') and error conditions when a table/plugin is unavailable, which goes beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each carrying useful information. The main purpose is front-loaded, and the description avoids repetition or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the read-only annotation and the absence of an output schema, the description still covers purpose, scope, types of artifacts, return shape, and error behavior. This is sufficient for an agent to understand what to expect and when to call the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'table' and 'limit' described. The description reinforces that counts are per artifact type, matching the schema's 'per artifact type' for limit, but it does not add substantial new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb ('List') and a well-defined resource ('every configuration artifact on a table'), enumerating the artifact types. It also distinguishes itself from CMDB CI impact, which helps differentiate it from other table-related 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/5Does 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 changing or removing' a table) and what it is not for ('not CMDB CI impact'). However, it does not name an alternative tool to use for CMDB CI impact, so it falls short of a fully explicit alternative recommendation.
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. The description adds the requirement of WRITE_ENABLED=true, which is valuable behavioral context beyond annotations. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the action and resource, and 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/5Given 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 fully covers the purpose, usage example, and a critical prerequisite. It is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, and the description repeats the schema's description (Array of { table, sys_id }). It adds no additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Delete' and the resource 'set of previously-created records', and distinguishes itself from the sibling tool bulk_create_records by mentioning the rollback_token. This makes the purpose clear and distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case (rollback from bulk_create_records) and a prerequisite (WRITE_ENABLED=true). It does not explicitly state when not to use, but the context is sufficient for most scenarios.
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, covering safety. The description adds valuable behavioral context beyond that: mentions validation of javascript: expressions against an allowlist, length limits, and common mistakes, plus the exact return shape. This is meaningful for an agent understanding what the tool does internally.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and contains no filler. Every clause adds information: what it checks, when to use it, and what it returns. This is a model of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description specifies the return format ({ valid, issues, suggestions }). It explains the key validation aspects and gives concrete examples of common mistakes. For a single-parameter read-only tool with good annotations, this is complete 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'query' is fully described in the schema with an example, giving 100% coverage. The description does not add extra parameter-level 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Lint-check' and targets a clear resource: 'ServiceNow encoded query' BEFORE running it. It also distinguishes itself from sibling query tools like query_records or fluent_query by focusing on validation rather than execution, and mentions specific checks (javascript: expressions, length limits, common mistakes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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 running it', implying it is a pre-flight check. It gives clear context for the use case but does not mention when not to use it or explicitly name alternatives among the many sibling tools, 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.
- 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 this with 'Read-only.' The description adds value by disclosing the multi-format output (chart data, Adaptive Card for Copilot Studio, markdown table, summary), which is behavioral context beyond the annotations. It doesn't detail pagination or the 'real-time' refresh behavior, but with two annotations covering the 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose and concrete examples, then output formats in a compact list. Zero wasted words. The 'Read-only' label is a useful single-word note at the end.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with full schema coverage (100%), complete annotations (readOnlyHint, openWorldHint), no output schema, and no nested objects, the description thoroughly covers the tool's purpose, output formats, and integration target (Copilot Studio). The examples for table and group_by values in the schema complement the description well. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with every parameter (table, group_by, query, limit, title, chart_type) having meaningful descriptions in the schema. The description adds the default chart_type ('column') implicitly via schema and clarifies that table examples are provided in the schema. The description itself does not go beyond the schema's parameter docs, so the baseline 3 for full coverage is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource: 'Build a real-time chart of ServiceNow records grouped by a field' with concrete examples (incidents by priority, cases by state). It clearly distinguishes from related siblings like visualize_trend (trend-over-time) and run_aggregate_query (raw SQL aggregation without visualization) by emphasizing chart-ready output. The read-only nature is stated explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states what it returns (chart data, Teams Adaptive Card, markdown table, summary) which indicates when to use it over alternatives like run_aggregate_query or trend_query. However, it does not explicitly name sibling tools as alternatives or state when NOT to use it (e.g., when you need raw data only, or want time-series trends). The 'Read-only' tag gives some usage context via annotations.
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 and openWorldHint=true, which already cover the safety profile. The description adds valuable behavior context beyond annotations: the substring/LIKE matching semantics, the limitation of scanning script-bearing config tables, and the inherent false-positive/miss tradeoffs. It doesn't disclose output format details, but the caveats are meaningful 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all packed with essential information: what it scans, when to use it, and the critical matching semantics caveat. No filler, no repetition of schema content. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only dependency analysis tool with full schema coverage, good annotations, and no output schema, the description covers the core concerns: scope of search, use case, and result interpretation pitfalls. Slightly more detail on return structure would help, but as a discovery/analysis tool the caveats matter more than output format, which the output schema absence makes the agent expect to be variable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters ('Artifact name to search for' and 'Max matches per source'). The description implies the 'name' parameter via the artifact context but adds little beyond the schema. Baseline of 3 is appropriate given full schema coverage and adequate schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states specific verb+resource (find what references a Script Include/named artifact) and clarifies it scans script-bearing config tables for textual use of the name. It explicitly distinguishes its use case (before renaming/deleting) from sibling tools like get_script_include or list_script_includes, which fetch content rather than analyze dependencies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it ('Use it before renaming or deleting a Script Include, Script Action, etc.') and provides critical caveats: substring/LIKE matching means false positives from comments/similar names and misses for dynamic references. This gives the agent clear decision criteria on when this tool is appropriate and how to interpret results.
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, openWorldHint), the description adds that it's executed via the SDK CLI, is new in version 4.8, and is browser-free. It also confirms read-only behavior. This provides additional context for agent decision-making.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus an example. It is front-loaded with the core action, followed by contextual use cases and a concrete example. Every element earns its place without superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage context, and an example. It does not explain the return format or prerequisites (e.g., SDK installation), but given the good annotations and schema, it is largely complete. Some details about expected output could be added.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents parameters. The description adds an example demonstrating usage of all four parameters (table, query, fields, limit), which provides practical context beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs 'now-sdk query <table>' as a read-only operation via the ServiceNow SDK CLI. It specifies the resource (table) and method (CLI query), with an example that distinguishes it from other query tools like 'fluent_query' or '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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'resolve sys_ids, inspect table schemas, check existing records, read choice values' during Fluent code authoring. It implies a development context but does not explicitly state when not to use it or mention 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, so the description adds value by stating it returns 'full details'. No contradictions; the description provides useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core purpose with no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and the tool's simplicity (single record retrieval), the description adequately conveys that it returns full details; it is sufficient for an AI agent 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter schema coverage is 100%, but the description clarifies that the number format is PRB... or sys_id, which adds meaning beyond the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Get' and resource 'problem' along with identifier types (number PRB... or sys_id), clearly distinguishing it from sibling get_* 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells when to use the tool (to get full details of a problem by identifier), but does not explicitly state when not to use it or provide alternatives; however, the context of the getter pattern makes it 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?
The description discloses the state transition to 'Requested' and the permission requirement (WRITE_ENABLED=true), adding behavioral context beyond annotations that indicate it is a non-destructive write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 14 words with no unnecessary information. It efficiently conveys the purpose and a key requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description covers the essential action, state change, and a requirement. It could mention error conditions or idempotency, but is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'sys_id' is described in the schema as 'System ID of the change request'. The description adds no additional meaning beyond what the schema provides, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: moving a change request to 'Requested' state for approval. It identifies the specific resource (change request) and the operation (submitting for approval), distinguishing it from siblings like 'create_change_request' and 'close_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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates when to use: to initiate approval for a change request. It mentions a prerequisite (WRITE_ENABLED=true) but does not explicitly compare with alternatives like 'approve_request'.
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. The description adds value by specifying supported APIs (GlideRecord, GlideQuery, etc.), that it returns script output, and the write requirement. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no wasted words. It front-loads the purpose, then lists capabilities, and ends with usage guidance. Each sentence serves a distinct purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers all critical aspects: what it does, what APIs it supports, when to use it, that it returns output, and a prerequisite. No output schema exists, so the explanation of return value is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 (scope and script). The description adds the hint 'Use gs.print() or gs.info() for output' and states 'Returns the script output', which is not explicitly in the schema. This helps the agent understand how to get results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes server-side scripts on ServiceNow, listing supported APIs and distinguishing it from REST-based tools. It explicitly says 'Use for complex queries that cannot be expressed via REST', which differentiates it from sibling tools like query_records or nlq_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear when-to-use scenario ('complex queries that cannot be expressed via REST') and a prerequisite ('REQUIRES WRITE_ENABLED=true'). However, it does not explicitly list when not to use it or name alternatives, but the context from sibling tools implies many specific tools exist for simpler 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 include readOnlyHint=true and openWorldHint=true, and the description complements rather than contradicts them. Beyond annotations, it discloses that script matches are substring (LIKE) based with false-positive/miss risks, and that results are candidate lists. Only minor gap: it doesn't describe return format or pagination behavior, but with read-only annotations covering safety, this is strong 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. First sentence delivers purpose and scope; second sentence delivers usage guidance and caveats. Every clause earns its place with actionable information. No repetition of schema content or annotation hints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with full schema coverage and good annotations, the description is complete. It explains what it searches, when to use it, how matches work, and their reliability. No output schema exists, but the caveat about candidates-not-definitive compensates for what a return-type spec might otherwise need to communicate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema_description_coverage is 100% (field, limit, table all documented in schema). The description's main param contribution is explaining the 'limit' semantic ('Max matches per source'), adding per-source meaning beyond the schema's generic default note. This adds modest value on top of a fully-covered schema, warranting the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Find where a table field is used' — specific and unambiguous. It enumerates the exact artifact types searched (dictionary entry, business rules, script includes, client scripts, UI actions, widgets), which distinguishes it sharply from sibling `find_script_references` (script-only) and `discover_table`. The purpose is fully specified with scope and intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context: 'Use it before renaming or removing a field.' This is a concrete, actionable trigger condition that tells the agent exactly when to invoke. It also clearly explains the match semantics (substring/LIKE) and caveats (false positives from comments, similarly-named symbols; misses for dynamically-built references), and instructs treating results as candidates to review not a definitive list. This is model usage 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?
Adds important behavior details beyond annotations: rollback deletes on failure, all-or-nothing, dry_run support. Annotations only provide readOnlyHint=false, so description fills gaps well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three front-loaded sentences with no wasted words, clearly conveying key points.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core aspects: bulk creation, rollback, dry_run, requirement. Could mention size limits but still complete given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% but description adds context on batch behavior and rollback token, enhancing understanding beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it creates many records in a single call, tracking sys_ids and returning a rollback token, distinguishing it from siblings like create_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions dry_run, rollback_on_error, and requirement WRITE_ENABLED=true, but doesn't explicitly say when to use vs single create or alternatives.
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 already indicate readOnlyHint and openWorldHint. The description adds that the tool runs an external command and emphasizes always-current documentation, which provides behavioral context beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action and a list of examples. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple schema and lack of output schema, the description adequately covers purpose, usage, and examples. It could mention output format, but the provided information is sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 100% with a description for the single 'topic' parameter. The description enriches this by listing many known topics, adding meaning beyond the schema examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 get live SDK documentation for Fluent APIs, types, patterns, and best practices. It lists many specific topics, distinguishing it from sibling fluent tools like fluent_build or fluent_query, 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing current API signatures rather than training-data guesses, but does not explicitly state when to avoid this tool or provide direct alternatives. It does provide a clear context and many examples, though missing explicit 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=true and openWorldHint=true. The description adds valuable behavioral context beyond annotations: it returns results ranked by relevance, and mentions the catalog size (400+ tools). There is no contradiction with annotations, but it could further detail ranking or output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three focused sentences. The first states the core functionality, the second gives usage guidance, and the third adds context. Each sentence earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (search with 2 parameters, no output schema), the description sufficiently covers purpose, usage, and parameters. It does not detail the output structure or ranking algorithm, but for a search discovery tool, that level of detail is acceptable and not critical for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by providing example keywords (e.g., 'create incident') and stating the default limit (25), which is not in the schema. This helps the agent understand typical usage beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool searches the full NowAIKit tool catalog by keyword to discover the right tool. It specifies the scope (400+ tools), the action (search by keyword), and the result (matching tool names + descriptions ranked by relevance). This distinguishes it from siblings which are direct operations on specific entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Use this FIRST when you are unsure which tool to call.' It also provides context about the MCP_TOOL_DISCOVERY=lean scenario, giving clear, actionable usage direction.
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 aligns with annotations (readOnlyHint, openWorldHint) and adds behavioral context: it is read-only, uses the public docs site, returns ranked results with specific fields. No contradictions; the description enhances the annotation information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey purpose, scope, output, and complementary tool. Front-loaded with the core action, no wasted words. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently explains return fields (title, breadcrumb, URL, snippet, ref) and the complementary tool. Annotations cover read-only and open-world aspects, making the description complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and descriptions are already good. The description adds value by providing concrete query examples ('GlideRecord addEncodedQuery') and indicating the product field is optional, which enriches understanding beyond bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches ServiceNow product documentation, listing specific content types (API references, guides, etc.) and output fields. It also distinguishes from sibling `fetch_servicenow_doc` by mentioning it as a complementary tool for reading full pages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool ('ground answers in current docs rather than memory') and notes it is read-only and uses the public site, not the instance. However, it does not explicitly exclude use cases or name alternative tools among the many siblings.
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 already declare readOnlyHint=true and openWorldHint=true. The description adds genuinely useful behavioral detail: results come back without 1000-row truncation, includes average resolution time automatically for task tables, durations are pre-formatted (with example '21 14:03:10'), and enumerates the full return payload (stats table, rows, count chart Adaptive Card, summary). This substantially exceeds the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense but front-loaded with the core distinction early. It packs many distinct pieces of value (no truncation, return types, format details, task-table behavior, array format flexibility) into a compact passage. Slightly long but every sentence contributes; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter aggregation tool with no output schema, the description is remarkably complete: it names all return components, explains the important task-table auto-average behavior, covers duration formatting, documents limit semantics, and contrasts against raw listing. Very little is left ambiguous for an agent considering this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds significant value: it explains avg_fields can be omitted for task tables to still get average resolution time, clarifies comma-separated strings are accepted for arrays, notes duration fields come pre-formatted, explains limit means 'top N groups by count', and gives an encoded query example format. This meaningfully enriches the schema-only understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs server-side aggregate grouping by a field in one query without row truncation, computing per-group counts and stats. It distinguishes itself from siblings by explicitly noting it avoids raw record listing and compares against run_aggregate_query/trend_query/visualize_aggregate context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'the right tool for a periodic summary like incident volume by category', gives concrete when-to-use guidance, and instructs 'Do NOT list raw records for this; use this', which clearly differentiates from list/query tools. Provides the example use case with avg_fields implication.
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:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/nowaikit'
If you have feedback or need assistance with the MCP directory API, please join our Discord server