ServiceNow Dev MCP

Server Quality Checklist

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

Latest release: v2.1.0
Disambiguation5/5
Each tool targets a specific resource and action, with clear phase prefixes (e.g., analyze_, build_, create_). Even within dense areas like migration, tools like discover_schema, build_artifacts, and run_full_migration are distinct. The platform prefixes (jira_, sf_, sn_) further separate concerns.
Naming Consistency5/5
Tool names follow a consistent verb_noun pattern in snake_case. Platform-specific tools are uniformly prefixed (jira_, sf_, sn_). Variations like test_code_file or map_users still adhere to the same structure. No mixing of camelCase or inconsistent verb forms.
Tool Count3/5
At 125 tools, the set is very large. While it covers a broad scope across multiple platforms (Jira, Salesforce, ServiceNow) and many functional areas (migration, testing, integration, code generation), the sheer number may overwhelm agents and increase selection complexity. Slight trimming or grouping could improve usability.
Completeness4/5
The tool surface is remarkably comprehensive, covering migration lifecycle, testing, integration, code review, and administration. Minor gaps exist: e.g., no direct tool for updating catalog items (only clone), and deletion tools are limited (e.g., no generic delete for most entities). Overall, core workflows are well-supported.
Average 4/5 across 125 of 125 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 1 community issues answered or closed in the last 6 months
- 86 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
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.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
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?
No annotations are provided, so the description carries the full burden. It mentions pulling live data but does not disclose side effects, permissions, rate limits, or that the tool is read-only. The output format is described, but key behavioral aspects are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first sentence followed by a bullet list of contents. It is informative without being overly verbose, though some minor redundancy exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (generating full documentation) and the absence of annotations and output schema, the description adequately covers the output structure but lacks details on parameter usage, behavioral context, and potential limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 60% (3 of 5 parameters have descriptions). The description adds no extra meaning beyond the schema; it does not explain how parameters affect the generated document or provide examples beyond the schema's brief descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates comprehensive technical documentation for a ServiceNow application, with a detailed list of contents. It distinguishes itself from sibling tools like 'generate_docs' or 'generate_migration_guide' by its specific focus on live data and full project documentation, though it does not explicitly contrast them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies use for generating full documentation but does not mention prerequisites, exclusions, 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?
Without annotations, the description only mentions 'Returns deploy-ready payload', which gives minimal behavioral insight. It does not disclose side effects, required permissions, or potential errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences that contain all essential information without redundancy. Front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description is insufficient. It lacks explanation of the return payload, parameter semantics, and usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only parent and roles have descriptions). The description adds no parameter-level details, failing to clarify the 'title' and 'description' parameters beyond the schema's structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('Service Catalog category (sc_category)'), identifying the specific table. It is distinct 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites, and no context on whether this is for initial setup or ongoing operations.
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?
No annotations provided. The description does not disclose permissions needed, idempotency, or behavior for edge cases (e.g., adding existing users). It adds trivial context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey purpose and action options. Could be improved by grouping or formatting, but no unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or mention of return values. Missing details on what the list action returns and success/failure behavior. Incomplete for a tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, and the description repeats the action enum but adds no new meaning for group_name or account_ids. Baseline score applies as description adds minimal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds, removes, or lists users from a Jira group. This distinguishes it from sibling tools like jira_create_group which creates a group, not manage members.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., sn_manage_group_members for ServiceNow groups). The action enum implies usage but lacks explicit 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?
No annotations are provided, so the description must fully disclose behavior. While 'query' implies read-only, it does not explicitly state that the tool has no side effects, require permissions, or detail return format. This is a gap for a read 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently communicates purpose and use cases. It is front-loaded with the action and resource, though structure could be slightly improved with separate guidance clauses.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema description coverage is high and no output schema exists, the description is adequate for a basic query tool. However, it lacks details about return format or pagination, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes all five parameters with descriptions, providing high coverage. The tool description adds context for usage but does not enhance parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries any ServiceNow table and lists specific use cases. It distinguishes from siblings that target specific records or operations, but does not explicitly differentiate from other query tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives example use cases (staging, migrations, incidents) but lacks explicit guidance on when not to use the tool or alternatives like sn_read for single records. Usage is implied but not comprehensively framed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It implies a read-only operation via 'Get', but does not explicitly state idempotency, side-effect-free behavior, or permissions needed. Minimal but acceptable for a simple retrieval.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence with no wasted words. Could include structured details (e.g., return format) but remains concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description should explain return format (e.g., array of value/label pairs) and important nuances like inclusion of inactive choices. It lacks these details, making it incomplete for a data-returning tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with brief descriptions for table and field. The description adds context by specifying these are for a ServiceNow table's choice list and gives examples, enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all choice list values for a specified field on a ServiceNow table, with helpful examples like state, priority, category. It distinguishes from sibling tools like get_dictionary_overrides or explore_table, though not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., create_choice, get_dictionary_overrides). The description only states what it does, not the 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?
No annotations provided, so description must compensate. It states append behavior but lacks details on side effects, target record requirements, error handling, or data format. Insufficient 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with primary action. Efficient use of words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, 3 required, and no output schema, the description is too brief. It lacks explanation of return value, error conditions, and parameter relationships, leaving gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25%. Description adds context that target is ServiceNow and comments are appended with author/timestamp, but does not explain source_ids, sn_table, or journal_field beyond default. Partial compensation for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'copies' and the resources 'source comments into ServiceNow target record's comments or work_notes journal', and appends author/timestamp. This differentiates from sibling tools like migrate_attachments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like migrate_attachments, no prerequisites or exclusions, and no mention of choosing between comments and work_notes via journal_field.
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?
With no annotations, the description must fully disclose behavioral traits. It mentions the tool is used for 'creating' and 'managing' groups/queues, implying mutations. However, it does not disclose required permissions, error states (e.g., duplicate group), side effects, or any destructive behavior. The description is insufficient for an agent to understand the impact of using this 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with clear front-loading of the main purpose. It uses bullet points for actions and use cases, making it scannable. No redundant information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, multiple actions) and lack of output schema, the description covers core actions and use cases. However, it misses details on required fields per action (beyond 'action'), error handling, and behavior for different parameters (e.g., what happens if group_id is invalid). The high schema coverage partially compensates, but completeness is only adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 86%, so the baseline is 3. The description adds the action enum list and brief context, but does not provide additional meaning beyond the schema parameter descriptions. It adds value by grouping actions but does not compensate for the uncovered 14%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates and manages Salesforce Public Groups and Queues, with a list of actions. It distinguishes from sibling tools like jira_manage_group_members and sn_manage_group_members via the 'sf_' prefix and explicit reference to Salesforce. However, it does not explicitly differentiate from other Salesforce tools like sf_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists actions and their purposes (create, create_queue, add_members, etc.) and provides use cases for groups/queues. However, it lacks guidance on when to use each action (e.g., when to use create vs create_queue) and does not mention prerequisites or context where this tool is preferred over alternatives.
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?
No annotations are provided, so the description must fully disclose behavior. It mentions generating a notification record, HTML template, plain text fallback, and checklist, but does not address side effects, idempotency, permissions, or what happens on errors. The 'best practice checklist' is ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise with three clear sections: purpose, recipient types, and generated outputs. The bullet-like lists are efficient, though they lack markdown formatting.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 12 parameters and no output schema or annotations, the description is incomplete. It fails to describe the return value, error handling, prerequisites, or what happens to existing notifications. The 'best practice checklist' is vague.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%; the description adds value by explaining recipient types (field, group, role, user) and the generated outputs. However, many parameters like category, reply_to, and email_script are not enriched beyond schema descriptions. Compensates partially.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a ServiceNow email notification with specific components (HTML template, recipients, conditions). It distinguishes from siblings like create_push_notification by specifying 'email notification'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains recipient types but does not provide explicit guidance on when to use this tool versus alternatives like create_push_notification or other notification tools. No when-not or comparison with siblings.
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?
No annotations are provided, so the description must convey behavioral traits. It only states the search action and use case, omitting read-only nature, potential rate limits, or result format. Basic, but insufficient for a fully informed selection.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first defines the action and filters, second provides usage context. Highly concise and front-loaded with the core purpose. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and moderate parameter count, the description provides adequate context for a simple search tool. However, it lacks details on output format (e.g., fields returned), pagination, or performance implications, which are common for debugging tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (3 of 4 params have descriptions). The description echoes 'by keyword, source, or level' but adds no extra meaning beyond the schema. The limit parameter is not mentioned in the description, relying solely on schema default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb (Search), resource (ServiceNow system logs/syslog table), and filtering dimensions (by keyword, source, or level). Sibling differentiation is implicit but not explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Useful for debugging Business Rules, integrations, and scheduled jobs', giving context. However, it does not specify when NOT to use this tool or suggest alternatives (e.g., for full table scans).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states 'Static analysis code review,' which implies a read-only, non-destructive operation, but it does not explicitly confirm this or address potential side effects, rate limits, or authentication needs. The implication is reasonable but not explicit, so it partially compensates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that efficiently lists check categories and the return value. It is front-loaded with the main purpose. While it could use bullet points for improved readability, it remains focused and without extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 params, no output schema), the description explains the return value (score 0-10, verdict, guidance) and covers major check categories. However, it does not detail the output structure, error handling (e.g., invalid script), or provide examples. It is adequate but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only 'script' has a description). The tool description adds meaning about what the review checks, but it does not explain the 'type' parameter (e.g., how it affects analysis) or the default value. The description fails to compensate for the missing schema documentation, leaving the agent unclear about the parameter's role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'Static analysis code review for a ServiceNow script' and lists specific check categories (critical, anti-patterns, performance, etc.), distinguishing it from siblings like test_code_file or analyze_performance. The verb and resource are specific, and the purpose is immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. It does not mention prerequisites, when NOT to use it, or when another tool (e.g., analyze_performance, test_code_file) would be more appropriate. The description only states what it does, leaving the agent without comparative 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?
No annotations exist, so the description must fully disclose behavior. It states it 'returns scripts ready to create', implying no direct modification, but does not confirm non-destructive nature or mention permissions, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph with bullet list, front-loaded with purpose. Efficient but the bullet list could be more structured. No wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complex tool with 5 params and no output schema. Description lists generated artifacts but lacks details on return format or usage instructions. Somewhat complete for a scaffold generator.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (80%), so baseline is 3. The description briefly references app_name and prefix but adds no meaning beyond the schema for other parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a complete application scaffold for ServiceNow, listing specific artifacts. This distinguishes it from sibling tools like create_update_set or 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when creating a new application but does not specify when not to use it or provide comparisons to alternatives. No exclusions or context on 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?
No annotations exist, so the description must fully disclose behavior. It states the tool returns a 'deploy-ready payload for the sys_choice table', implying it may not directly insert the record. However, the phrase 'Add a new choice value' suggests mutation, creating ambiguity. The description does not disclose side effects, permissions, or whether the operation 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each valuable: first states the action, second clarifies the output, third lists common uses. It is front-loaded and contains no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description should be more complete. It omits important details like error handling, prerequisites (e.g., table must exist), and whether the operation is transactional. The ambiguity about 'deploy-ready payload' leaves the agent uncertain about the tool's effect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are documented in the schema. The description adds no additional meaning to any parameter, merely listing common uses that indirectly hint at values. This meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and the resource 'a new choice value to a field's choice list in ServiceNow'. It specifies the platform and gives common use cases, making the tool's purpose unmistakable. It distinguishes itself from sibling creation tools by its specific domain (choice values).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus alternatives. It only mentions 'common use' but does not provide when-not-to-use scenarios or compare with other tools like update_choice or delete_choice. The agent is left to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. 'Fetch' implies a read operation, but the description does not mention authentication, rate limits, error handling, or the return format. It lacks essential behavioral context beyond the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a single sentence that front-loads the essential action. There is no wasted content, and every word contributes to defining the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description captures the basic action but omits details such as whether the result includes full items or just variables, and any constraints. It is minimally complete but could provide more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter, and the description does not add new meaning beyond what the schema already provides. The baseline score of 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a catalog item and its variables, using specific verbs and the resource. It distinguishes from sibling tools like clone_catalog_item by specifying the purpose 'for inspection or cloning'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for inspection or cloning, but does not explicitly state when to use this tool over alternatives, nor does it provide exclusions. The usage context is implied by the purpose, but no direct guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
In absence of annotations, the description discloses polling behavior and a 5-minute timeout, but does not state whether the operation is read-only or has side effects, nor mention rate limits 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, no filler, front-loaded with key information, and efficiently conveys purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers purpose and timeout, it omits the return value (expected progress information) and does not document the parameter, leaving an agent without complete context for a simple monitoring tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fails to mention the 'max_wait_seconds' parameter or explain its role, despite referencing the default timeout implicitly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool polls active import set runs until completion or timeout, and explicitly provides usage context ('Use after kicking off a bulk migration'). This distinguishes it from siblings like 'run_full_migration' or 'check_migration_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear when-to-use hint ('after kicking off a bulk migration'), but does not specify when not to use or mention alternative monitoring tools (e.g., 'check_migration_state', 'verify_migration_counts').
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?
No annotations provided, but the description explicitly states 'no record is persisted', disclosing a key non-destructive behavior. This adds value beyond the structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no redundant words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 required params, no output schema, and no annotations, the description covers purpose and usage context but lacks parameter descriptions and output details, leaving gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain any parameter. It mentions 'staging row' and 'transform map' but provides no details on the three required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Shows what target fields will be set' and the resource 'when a staging row is transformed'. It is specific but does not explicitly distinguish from the sibling tool 'transform_preview'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context 'after build_artifacts' but no alternatives or when-not-to-use. The guidance is adequate 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?
No annotations provided so description carries full burden. It explains watermark usage and first-run behavior but lacks details on concurrency, error states, or side effects beyond migration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences, no redundancy. Front-loaded with key behavior, earns its place with essential info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 required params, no output schema, and no annotations, the description is too brief. Lacks details on return format, error handling, or post-run state, which are critical for a migration tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 40% schema coverage (platform, watermark_key described). Description adds no parameter context for object_or_project, sn_table, staging_table, leaving the agent guessing their meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs a delta sync migration using a watermark, contrasting with run_full_migration sibling. Specific verb (migrate) and resource (records that changed) with first-run behavior noted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. The first-run context is implied but no alternatives or exclusions are mentioned given siblings like run_full_migration.
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?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. The description lists what artifacts are created but does not state whether the tool is idempotent, whether it overwrites existing artifacts, if it requires specific permissions, or what side effects (e.g., destructive) might occur. This is a significant gap 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear phase label, a list of artifacts, a usage condition, and a post-action instruction. It is front-loaded with the purpose. While slightly verbose, it is efficient and each sentence serves a purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and incomplete parameter descriptions, the description is not complete enough. It does not explain what the tool returns (only 'show artifact summary'), nor does it cover behavioral aspects like error handling or state changes. The agent lacks critical context for a tool that creates multiple artifacts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, meaning two parameters ('object_name' and 'sn_table') lack descriptions in the schema. The description does not compensate; it only mentions the high-level purpose and does not explain how these parameters are used. For example, 'object_name' and 'sn_table' are not elaborated. The description adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Phase 4: Create all migration artifacts in ServiceNow: staging table + columns, transform map, field maps, transform scripts, data source, REST message.' It specifies the set of artifacts and labels it as the final phase, differentiating from sibling tools like 'discover_schema' or '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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit and actionable usage guidance: 'Only call this after Checkpoint 1 (schema) AND Checkpoint 2 (mappings) are both approved by the user.' It also instructs on what to do after completion: 'show the artifact summary and ask the user to verify in ServiceNow (Checkpoint 3).' This covers when to use and what to do next.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It explains the tool generates a plan with test cases and does not execute anything (present for approval). However, it does not mention whether the plan is stored or how it is returned, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence followed by detailed bullet points of all 8 phases. It is somewhat verbose but each point serves to clarify the output. The main purpose is front-loaded, though the phase details could be more concise without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, nested objects, no output schema), the description lacks explanation of how input parameters influence the generated plan. It thoroughly describes the output but omits the relationship between inputs and outputs, leaving the agent uncertain about parameter usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 57%. The description does not elaborate on parameter meanings or usage beyond what the schema provides. Key parameters like 'analysis', 'field_mappings', and 'transform_rules' are not explained in context, so the description adds minimal value to parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'generate' and the resource 'full expert migration test plan', with a specific audience and goal ('for user approval before executing'). It details the 8 testing phases, making it distinct from sibling tools like 'create_test_plan'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance: 'Present the plan to the user for approval, then call run_approved_tests'. This gives a workflow context. It does not explicitly exclude alternatives but the specificity of 'migration test plan' differentiates it from generic test plan 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?
No annotations are provided, so the description carries the full burden. It mentions generating deploy-ready payload and best practices but lacks details on potential side effects (e.g., overwriting existing widgets), permission requirements, or failure modes. The statement is comprehensive 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and sub-bullets, front-loading the main purpose. Each sentence adds value without redundancy. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers generated artifacts and return payload components but omits details on tool prerequisites (e.g., required instance configuration), output format structure, or constraints like rate limits. For a complex tool with no output schema, this leaves some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 43%, a significant gap. The description does not elaborate on parameter meanings beyond what the schema already provides. For example, 'fields' and 'actions' are mentioned in generated sections but not explained in terms of parameter usage. The description fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a complete, production-ready Service Portal widget from a requirement description. It lists all generated sections (HTML, CSS, Client script, Server script, Option schema) and distinguishes from siblings like update_widget and clone_widget by implying it creates new widgets from scratch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating new widgets but does not explicitly state when to use this tool versus alternatives (e.g., update_widget, clone_widget). No guidance on prerequisites or scenarios where 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?
No annotations are provided; the description discloses the core behavior (copying attachments) but lacks details on permissions, error handling, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences that front-load the purpose, containing no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, yet the description does not explain return values or handle edge cases like missing correlations, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, and the description does not add meaning for the undocumented 'sn_table' parameter or elaborate on expected formats for 'source_ids'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool copies attachments from source records to ServiceNow target records using a correlation_id, which distinguishes it from sibling tools like migrate_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for migrating attachments but does not explicitly state when to use it 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?
No annotations; description only states basic listing behavior. Does not explain the limit parameter or any pagination/rate limits. Missing depth for a simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences, no fluff, front-loaded with purpose and usage hint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a list tool, but missing details on limit behavior and output format. Ties to sibling adds context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only half of parameters (keyword) are covered in schema description; description adds that keyword is optional but ignores limit. Does not compensate for missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists ServiceNow roles with optional keyword filter. Directly ties to sibling sn_assign_roles, differentiating 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says useful before sn_assign_roles, giving clear context. Does not mention when not to use or alternatives beyond that.
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?
With no annotations provided, the description must fully disclose behavioral traits. It mentions actions but omits details like idempotency, permissions required, error handling, or return format of list action. This is insufficient 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient: one introductory sentence plus a bullet list of actions. Every sentence serves a purpose, and the core functionality is front-loaded. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, 3 actions) and lack of output schema, the description covers the main operations. It indicates that members are required for add/remove. However, missing details like list return format or behavior for duplicate/absent members slightly reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%. The description adds marginal value: it clarifies that 'members' is required for add/remove and mentions 'one or more users', but largely repeats schema information. No additional syntax or format details are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds/removes members or lists current members, with explicit action options. It distinguishes from sibling tools like sn_create_group or jira_manage_group_members by focusing on ServiceNow group member management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists actions but does not provide guidance on when to use this tool versus alternatives. For example, it doesn't clarify when to use this vs. sn_create_group or sn_get_group. 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?
With no annotations, the description carries full transparency burden. It explains each mode's action but omits behavioral traits such as read-only status, required permissions, side effects, error handling, or parameter dependencies (e.g., table required for suggest_indexes). The absence of output schema also obscures return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with a one-line summary, and structured as a bullet list. Every sentence adds value without repetition. The format is easily scannable for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite covering the main purpose and modes, the description lacks details on mode-specific parameter requirements, output format, and result interpretation. For a tool with 6 parameters and 5 modes, this leaves gaps in completeness, especially without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning to the mode parameter by detailing each option. For other parameters (table, minutes_back, threshold_ms, hours, limit), the description implicitly relates them to specific modes but does not provide full semantics. Given 50% schema coverage, the description compensates moderately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool analyzes ServiceNow instance performance and lists five distinct modes with clear, specific explanations (e.g., 'Find slow Business Rules and scripts from syslog (last N minutes)'). This distinguishes it from sibling tools like health_check_instance or get_audit_stats, which have different foci.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives. It lacks explicit scenarios, prerequisites, or comparisons to other tools like analyze_dependencies or health_check_instance. Users must infer usage from the mode descriptions.
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?
No annotations are provided, so the description must fully disclose behavior. It mentions 'Returns deploy-ready payload with best-practice template,' but fails to indicate side effects like creating a record in sys_script_email, required permissions, or that it does not deploy directly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with purpose, and uses bullet points efficiently. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters, no output schema, and no annotations. The description covers purpose and usage context but lacks details on return format, side effects, or prerequisites. Adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (description for 'description' is missing). The description adds little beyond the schema; 'logic' is already described as 'Core logic to embed (pseudo-code is fine)'. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Generate a ServiceNow Email Script (sys_script_email) for dynamic notification logic.' It lists specific use cases (dynamic recipients, conditional subjects, etc.) and the resource type is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit conditions for using the tool: 'used when a notification needs: Dynamic recipients...' It implies appropriate contexts but does not explicitly mention when not to use it or alternatives like create_notification for simpler 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?
No annotations exist, so the description must convey behavioral traits. It states output is a 'quick one-page technical spec', implying non-destructive generation, but omits permissions, rate limits, or side effects. For a generation tool, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three well-organized sentences: purpose, content areas, and use cases. Every sentence adds value with no redundancy or extra words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, 0% parameter coverage, and nested objects in the input schema, the description should provide more detail on parameter format and behavior. It lacks explanations for required nested structures (e.g., business_rules requires name and table), leaving the agent without enough context to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description only lists high-level categories (tables, business rules, etc.) without explaining individual parameters or nested object structures. The agent lacks guidance on how to populate fields like business_rules or script_includes, failing to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a quick one-page technical spec for a specific feature or change, listing covered areas like tables, business rules, script includes, notifications, and test plan. This distinguishes it from related siblings like generate_project_doc (for projects) and generate_docs (more generic), 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends use for sprint documentation, change requests, or PR descriptions, providing clear context. While it does not explicitly state when not to use or name alternatives, the use cases imply it's for small, scoped features, differentiating from broader doc 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?
No annotations are provided, so the description must carry the full burden. It only states the basic operation (create record) and return value (Id), but does not disclose side effects, authorization needs, rate limits, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two short paragraphs and clear examples. Every sentence is informative, and it is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers basic purpose and return value with helpful examples, but lacks details on error handling, rate limits, or authorization. For a simple create tool, 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.
Parameters4/5
Does 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 with examples showing typical field-value pairs for common objects, which helps the agent understand usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a record in any Salesforce object, with explicit examples. It distinguishes from siblings like sf_create_user (specific to User) and sf_update (update vs create).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for creating records in any object but does not explicitly state when to avoid using it or compare with alternatives like sf_create_user. No when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It implies the tool is a preview (non-destructive) but does not explicitly state it is read-only or describe side effects. Basic transparency but lacks explicit safety guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: four sentences packed with purpose, usage context, and examples. No wasted words, and the most critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description does not describe the return format or structure. For a tool with complex nested input parameters, this omission leaves a gap. However, the main use case and behavior are sufficiently covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by listing example transformation types and supported presets, which complements the schema. However, it does not explain the nuances of each rule property beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies field transformation rules to a sample set and returns transformed output. It specifies the verb 'apply', the resource 'transformation rules', and the output. However, it does not differentiate from the sibling tool 'preview_transform', 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool to verify transforms 'BEFORE running the full migration', providing clear usage context. It also lists supported built-in presets. However, it does not mention when not to use it or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral transparency. It implies read-only analysis ('fetches and analyses'), but does not explicitly state if it has side effects, requires specific permissions, or has any rate limits. The lack of disclosure is a significant gap for a tool that produces a plan for building.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two short sentences, front-loaded with the core purpose, then a clear list of return fields, followed by an actionable instruction. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters and no output schema, the description covers purpose, return fields (trigger type, conditions, actions, automation vs manual), and a post-call workflow. It could be improved by clarifying the output structure or error handling, but overall it is sufficiently complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have descriptions in the schema (100% coverage). The description adds useful context, especially for rule_id by noting it comes from a sibling tool (list_jira_automations), and provides examples for sn_table. This adds meaning beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states action (fetches and analyses), resource (specific Jira Automation rule), and output (migration plan for ServiceNow). It distinguishes from sibling analysis tools by specifying the context of Jira Automation to ServiceNow migration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides post-call workflow instruction ('present the plan and ask for confirmation before building'), which implies when to use this tool in a sequence. However, it lacks explicit guidance on when to use this versus alternative analysis tools (e.g., analyze_flow, analyze_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?
Without annotations, the description carries full burden. It explains it fetches live data and returns a deploy-ready copy, but is ambiguous about whether it actually creates the item in ServiceNow or just returns data. Side effects, permissions, and error cases are not disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (5 sentences) and well-structured, with a clear initial sentence followed by a bullet-like list of copied elements. Could be slightly tighter but is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description adequately covers inputs and process but lacks details on output format (deploy-ready copy meaning) and error handling. Moderate completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with brief descriptions. The description adds value by explaining what fields and variables are copied and that modifications override any field, which enriches understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool clones an existing Service Catalog item, listing what is copied (fields, variables) and that it returns a deploy-ready copy. This distinguishes it from create_catalog_item and clone_widget.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for cloning existing items but does not explicitly contrast with create_catalog_item or provide when-not-to-use scenarios. No alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It lists generated artifacts and states return order, but does not disclose side effects (e.g., overwriting, idempotency), authentication requirements, or potential errors. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main purpose, followed by a clear bullet list of generated outputs. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description covers the main functionality and output format. It lacks edge cases or prerequisites but is largely 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (descriptions for 'name' and 'url_suffix', but not for 'description' or 'pages'). The description adds context about what the tool generates but does not provide detailed semantics per parameter. It meets the baseline for moderate coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Scaffold a new Service Portal with theme, default pages, and best-practice CSS variables.' It clearly identifies the verb (scaffold/create) and resource (Service Portal), distinguishing it from sibling tools like create_catalog_item or scaffold_application.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating portals but does not specify when to use this tool versus alternatives, nor does it mention when not to use it. No exclusions or alternative tools are referenced, leaving guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool creates a record (push notification) and returns a deploy-ready payload. It also mentions token support in title and body. With no annotations provided, this covers key behavioral aspects, though it lacks details on required permissions or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences: purpose, return value, and additional detail about tokens. No unnecessary words or repetition. Well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, no output schema, no annotations), the description provides a clear purpose, return value, and token support. It is fairly complete, though it could mention prerequisites or the effect of the 'condition' parameter more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83%, with most parameters having descriptions. The description adds context about ${field} tokens in title and body, which supplements the schema. However, it does not add meaning to parameters like 'condition' or 'route_to' beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a ServiceNow push notification for the Now Mobile app. It mentions the return value (deploy-ready payload for sys_push_message table), but does not explicitly distinguish from the sibling 'create_notification' which likely handles email notifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for mobile app notifications by stating 'for the Now Mobile app', but it does not explicitly state when to use it versus alternatives like 'create_notification'. 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?
No annotations are provided, so the description carries the full burden. It discloses that re-activating Business Rule, Scripted REST API, and retry scheduled job occurs, offering some insight into what gets changed. However, it does not mention side effects, prerequisites, or idempotency, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 18 words, front-loaded with the verb 'Resume'. Every word contributes meaning without redundancy. It is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description adequately explains the tool's action and scope. It could be improved by noting idempotency or what happens if the integration is already active, but overall it provides sufficient context for selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (prefix) with schema description coverage at 100%. The tool 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resumes a paused bidirectional integration by re-activating specific components. This distinguishes it from sibling tools like disable_integration which would suspend or retry_failed_syncs which retries syncs rather than re-enabling the whole integration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an integration is paused via the phrase 'Resume a paused...' but does not explicitly state when to use this tool versus alternatives like retry_failed_syncs or disable_integration. No exclusions or 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?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It correctly indicates this is a read operation by stating 'Return current audit trail statistics,' but it does not disclose potential side effects, authorization requirements, rate limits, or data freshness. The information is adequate 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is composed of two concise sentences. The first sentence states the core purpose, and the second provides specific outputs. Every sentence is informative and without extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no parameters, no output schema). The description enumerates the key output fields (counts of created, updated, skipped, errored records, average time). It lacks an explicit statement about the return format (e.g., JSON object), but for a low-complexity tool, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is an empty object, so schema description coverage is trivially 100%. The description adds no parameter information because none is needed. Per guidelines, for 0 params, the baseline is 4, and no value is added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the resource 'current audit trail statistics' for the active migration session. It specifies the types of counts provided (created, updated, skipped, errored) and average time per record, making the tool's purpose distinct from siblings like check_migration_state or verify_migration_counts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, nor any when-not-to-use conditions. The description implies usage for retrieving audit stats, but does not mention when other tools like verify_migration_counts would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states 'Get the full guided fix', which implies a read operation, but does not explicitly confirm no side effects, no destructive actions, or any other behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no redundant information. The key information is front-loaded, and every part serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter and no output schema, the description adequately explains what the tool returns ('full guided fix'). It is complete enough for use, though it could be slightly improved by mentioning the response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with a description and examples. The tool description repeats the examples but does not add new semantic 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'full guided fix for a specific known issue by its ID', with examples like 'BR001'. It distinguishes from siblings like 'list_common_issues' by establishing a prerequisite 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs users to 'Use list_common_issues first to find the ID', providing a clear prerequisite. It does not list alternatives or when not to use, but the guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the inability to create users directly and mentions the group creation and membership functions. However, it does not specify permissions needed or behavior if the group already exists, which are gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences: purpose, context, and a critical note. No fluff or redundancy, though it could be slightly more structured by separating the note more clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool with no output schema and no annotations, the description explains the core function and a key limitation. However, it lacks details like default behavior if the group exists, required permissions, or return value, making it moderately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for both parameters. The description adds minimal value beyond the schema, just mentioning optional member addition. A baseline of 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a Jira group and optionally adds members, with the verb 'create' and resource 'Jira group'. It distinguishes from siblings like jira_manage_group_members, which handles existing groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool (group creation) and includes an important note about user creation limitations via Atlassian Admin. However, it could more explicitly state when to use this vs. jira_manage_group_members.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool performs read operations and provides usage examples, but does not mention idempotency, response format, error handling, rate limits, or authentication requirements. The examples help but leave behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, a bulleted list of resource_type options, and multiple examples. It is front-loaded and each element serves a purpose. Minor redundancy (e.g., repeating 'resource_type=' in examples) keeps it clear but not overly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 resource types) and lack of output schema, the description covers each resource type with an example and key parameters. However, it omits details about default values (e.g., limit=20), optional fields, pagination, and response structure, leaving some gaps for a comprehensive understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant value beyond the schema by mapping each resource_type to the appropriate parameters with concrete examples. For instance, it clarifies that 'issue' requires 'issue_key', 'search' uses 'jql', and 'user' uses 'query'. This conditional parameter usage is not evident from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read Jira issues, projects, users, or boards' with a specific verb and resource scope. It then lists all 8 resource_type options with brief explanations, effectively distinguishing this read tool from sibling write tools like jira_create, jira_update, and jira_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit usage guidance through examples for each resource_type (e.g., 'resource_type="issue" issue_key="KAN-42"'). However, it does not explicitly state when to use this tool versus alternatives, nor does it provide any 'when not to use' or exclusionary context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the three update behaviors (fields, transition, comment) and gives example field structures. No annotations exist, so the description carries full burden. It lacks details on permissions, error conditions, or side effects (e.g., whether fields are merged or overwritten).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose, followed by clear enumeration of update_type options and examples. It is concise with no redundant sentences, though the examples could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain return values or indicate what the tool returns after an update (e.g., updated issue details). It covers the main operations but omits error handling or confirmation of success. Adequate for common use but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 83% of parameters with descriptions, but the description adds value by showing concrete field update syntax (e.g., priority:{name:'High'}) and how to use transition_id with jira_read. This goes beyond the schema's generic 'Fields to update' description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a Jira issue or transitions it to a new status, with three enumerated update types. It distinguishes from sibling tools like jira_create or jira_delete by focusing on modification operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples for each update type and references jira_read for transition IDs, implying when to use each. However, it does not explicitly state when not to use this tool or compare it with alternatives like jira_delete for removing issues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the core action (re-firing Business Rule) and dry_run capability, but does not address potential side effects, prerequisites, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with purpose, followed by mechanism and dry_run advice. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers the tool's function and dry-run mode. It lacks details on return values and error handling, but is sufficient for a relatively simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (3 of 4 parameters have descriptions). The tool description reinforces dry_run but adds no new semantic value beyond 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('retry all failed sync attempts') and the resource ('integration error/retry table, Business Rule'). It is specific and distinguishable from sibling tools like run_delta_sync.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the dry_run option for testing, providing some usage guidance. However, it lacks explicit when-to-use vs. when-not-to-use, and does not compare to 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?
No annotations are provided, so the description carries the full disclosure burden. It mentions that username must be globally unique, but does not discuss side effects, idempotency, authentication requirements, or error behavior. For a creation tool, more transparency about expected outcomes and constraints would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise, using a single paragraph with line breaks for readability. However, embedding the SOQL example directly makes it slightly less structured. Every sentence adds value, but a more structured format could improve clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 15 parameters (5 required) and no output schema, the description provides the absolute essentials but lacks explanations for many parameters, return values, or error handling. It is adequate for basic use but incomplete for complex scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (27%). The description adds value by listing required fields and clarifying username format, but does not cover many optional parameters. It partially compensates by providing an external reference for profile_id, but overall, many parameters remain undescribed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a Salesforce user, listing required fields and providing a practical example for obtaining ProfileId. It distinguishes this tool from sibling tools like sf_create (which likely handles generic objects) and sf_update, making its specific purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists required fields and instructs users to get ProfileId via sf_read before using this tool, providing a concrete SOQL query example. It implies a prerequisite but does not explicitly state when to avoid using this tool or compare with 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?
With no annotations provided, the description carries full burden. It states the tool returns members, roles, and manager, but does not disclose that it's read-only, any permission requirements, or potential limits (e.g., pagination for large groups). Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 12 words, no redundancy. Front-loaded verb and resource. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 required param, 2 optional booleans) and no output schema, the description covers the key return data (members, roles, manager). Missing mention of read-only nature, but sufficient for this simple lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%), so the description must compensate. It mentions 'members, roles, and manager,' which hints at the boolean parameters (include_members, include_roles), but does not explain defaults or their effect. Partial compensation, but could be clearer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Look up') and resource ('ServiceNow group'), and lists the key details returned (members, roles, manager). It clearly distinguishes from sibling tools like sn_create_group or sn_manage_group_members.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when group details are needed but provides no explicit guidance on when to choose this tool over alternatives, nor any exclusions or prerequisites. Usage context is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It mentions the output is Markdown text, but does not disclose whether instance access or authorization is needed, or if the tool is purely generative without side effects. Behavioral traits like read-only nature are implied but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one paragraph front-loaded with the main purpose, followed by a clear list of targets. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (14 parameters, nested objects) and no output schema, the description explains the main function and doc_type options well, but does not map many parameters to their usage contexts (e.g., which params apply to which doc_type). Completeness is adequate but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for the doc_type parameter by listing and explaining enum values. However, schema description coverage is low (21%), and the description does not explain other parameters like when, events, condition, or components. Thus, only partial compensation for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates Markdown documentation for ServiceNow artifacts and lists specific doc targets with what each includes (e.g., script_include: 'Full API reference with method signatures'). It distinguishes itself from sibling tools like generate_feature_doc or generate_migration_guide by focusing on artifact-specific documentation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists the supported doc targets, indicating when to use the tool. However, it does not explicitly state when not to use it or recommend alternatives. The context is clear but lacks 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?
No annotations provided. The description does not disclose any behavioral traits beyond listing, which is appropriate. It adds minimal context beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at two sentences, front-loaded with the key action and benefit. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with one optional parameter and no output schema, the description adequately covers the purpose and what the output includes (descriptions and fix guidance). It is sufficient but could mention the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the optional 'category' parameter, and the schema has no description for it (0% coverage). While the parameter's enum values are self-explanatory, the description fails to add value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all code review rules with descriptions and fix guidance. It distinguishes itself from the sibling tool 'review_script' by noting it is useful for understanding what that script checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description hints at when to use this tool ('before running review_script') but does not explicitly state when not to use it or provide alternative tools. However, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses it creates a Fix Script record, runs as admin, and warns about safety. However, lacks detail on execution side effects, output, or error handling. Without annotations, transparency is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with three short sentences, front-loading important info (IMPORTANT), and no superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description adequately covers purpose and safety but omits expected output or how to verify execution. Dry run explanation helps, but post-execution behavior is unclear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds limited value beyond schema. It reinforces the dry_run parameter's purpose but does not deepen understanding of name or script parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a server-side script in ServiceNow using the Background Scripts table, with specific verb and resource. It distinguishes from sibling tools that are unrelated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage guidelines: only use safe, tested scripts and always dry run first. Does not explicitly mention when not to use or alternatives, but context is sufficient for safe usage.
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?
No annotations are provided, so the description carries the full burden. It discloses the checks performed and return structure, implying a read-only analysis. However, it does not explicitly state that it is non-destructive or mention permissions/performance implications, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured. It starts with the main purpose, uses a bullet list for readability, and contains no superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter analysis tool with no output schema, the description sufficiently explains inputs, checks performed, and output type (inventory plus issues/recommendations). However, it could mention any limits or return format specifics for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; the description adds minimal extra meaning beyond the schema's parameter description. The tool description repeats the table focus but does not provide additional syntax or format details, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it analyzes active email notifications for a ServiceNow table, listing specific checks (conditions, recipients, weight, subjects) and outputs (inventory plus issues/recommendations). This distinguishes it from sibling tools like analyze_dependencies, analyze_flow, 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for analyzing notifications but does not explicitly state when to use it versus alternatives, nor does it provide when-not or prerequisite context. Usage is implied but not guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It implies read-only behavior ('inspect', 'report') but does not explicitly state side effects or error conditions. Adequate but not fully explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences and bullet points. It front-loads the purpose and presents information efficiently with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description covers what the tool does, its inputs, and when to use it. It could briefly mention the return format but is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the one parameter (transform_map_sys_id) with a description. The tool description adds usage context but no additional meaning to the parameter. 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inspects a transform map, listing specific outputs like field maps, scripts, issues, and suggestions. It distinguishes from sibling 'analyze_*' tools by focusing on transform map auditing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'after build_artifacts or to review a manually built one.' While it doesn't list exclusions, the context is clear and sufficient for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes the return as a gap analysis of what exists, missing, and needs adding. It does not explicitly state the tool is read-only or discuss permissions/rate limits, but the inspection nature is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph of 4 sentences. It front-loads the purpose, then provides usage advice, return summary, and scope. Every sentence is necessary and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's role in migration workflow and the number of sibling tools, the description sufficiently orients the agent. It explains the return (gap analysis) and scope (any platform/table). Minor gap: no mention of error handling or empty results, but adequate for a pre-build check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context by mentioning 'source→target combination' and emphasizing flexibility ('Works for ANY source platform and ANY ServiceNow target table'), but does not elaborate on individual parameter formats or the optional staging_table.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Inspect ServiceNow to see migration artifacts') and the specific source→target combination. It distinguishes from siblings by explicitly advising to call before build_artifacts and by noting it works for any platform and target table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use: 'Call this at the very start of any migration session (before build_artifacts) to avoid re-creating things.' It does not list when not to use or provide direct alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly indicates a destructive action (deletion) and the condition for deletion. However, with no annotations, it lacks details on idempotency, error handling for invalid 'days_old' values, or any side effects. The description is adequate but minimal in disclosing 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and condition, followed by a brief rationale. Every word earns its place, with no redundancy or irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the action, condition, and rationale. It could mention safety (e.g., whether it's safe to run on production) or prerequisites, but it is largely complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'days_old' parameter by stating 'older than the given number of days', which the schema lacks (0% description coverage). It explains the parameter's purpose, though it could be more precise about constraints like positive integer or allowed range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Deletes' and the resource 'completed sys_import_set_run records', along with the condition 'older than the given number of days'. This distinguishes it from siblings like 'cleanup_artifacts' and 'cleanup_migration' which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a periodic maintenance use case with 'Run periodically to keep the instance healthy', but it does not explicitly state when to use this tool versus alternatives like 'monitor_import_set_progress' or other cleanup tools. 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?
With no annotations, the description carries full burden. It describes the effect (exportable as XML) but does not explicitly state irreversibility or state change. Adequate but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding value: purpose, benefit, usage context. Front-loaded and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one required parameter and no output schema, the description is sufficient. References sibling tool 'build_artifacts' for context. Could add more about typical workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter description. The tool description does not add additional meaning beyond 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Mark as complete' and the resource 'ServiceNow Update Set'. It distinguishes from siblings by specifying the completion action in the context of migration setup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this after build_artifacts is done and the user has verified everything looks correct,' providing clear usage context. However, it does not mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It states that the tool 'Returns connection status and instance URLs,' implying it is a read-only test. However, it does not explicitly confirm non-destructiveness, permissions required, or error behavior (e.g., what happens on failed connection). This leaves some ambiguity for a tool with no annotation safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four concise sentences with no unnecessary words. The first sentence immediately states the core purpose, and subsequent sentences add critical usage guidance and return information. Every sentence earns its place, making it easy for an AI to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 optional parameter, no output schema), the description adequately covers purpose, when to use, parameter context, and return value. It is missing details on error handling or side effects, but for a simple test tool this is sufficient. A score of 4 reflects minor gaps in a complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a single parameter (platform) including an enum description. The description adds context by saying 'Test live connections to one or all platforms,' which reinforces the parameter's purpose but does not provide additional semantic detail beyond the schema. Baseline is 3, and the description is adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Test live connections to one or all platforms using credentials already stored in .env.' The verb 'test' and the resource 'live connections' are precise, and the scope is explicitly defined as 'one or all platforms.' This distinguishes it from sibling tools like connect_jira and connect_salesforce, which likely establish specific connections rather than test existing ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage guidance: 'Call this after get_config to verify connections are working' and 'Do NOT ask the user for any credentials before calling this.' This tells the AI when to invoke the tool and what not to do. However, it does not explicitly mention when to avoid this tool in favor of sibling connect_* tools or other alternatives, so it loses one point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It mentions that credentials are 'held in memory for this session only — never stored or logged,' which is a key security detail. However, it does not describe potential side effects like overwriting an existing connection, error handling, or whether the tool tests connectivity before returning.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-line purpose, separate sections for WHEN TO CALL and HOW TO ASK THE USER, and a follow-up instruction. It is front-loaded with the main purpose, concise, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description instructs the agent to tell the user whether the connection succeeded and which instance was connected to, providing a complete flow. However, it omits details about error conditions or the exact return format, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with each parameter already described in the input schema. The tool description repeats these parameters in a user-facing format but adds no new semantic meaning beyond the schema, only the security note which pertains to behavior rather than parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Connect to a ServiceNow instance in one step,' specifying the verb (connect) and resource (ServiceNow instance). This distinguishes it from sibling tools like connect_jira and connect_salesforce, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'WHEN TO CALL' section that explicitly states to call at the start of any session needing ServiceNow access or when get_config shows servicenow.configured = false. This provides clear context for when to use the tool, though it does not list alternatives or exclusions explicitly.
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 no annotations provided, the description carries full transparency burden. It clarifies that the tool 'generates' payloads for deployment rather than directly creating records in the instance, which is a key behavioral distinction. However, it does not mention idempotency, authentication needs, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the core purpose, and uses bullet points for variable types and return payloads. Every sentence adds unique information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (10 parameters, no output schema), the description compensates by detailing the return payloads (item, variables, scripts, policies) and providing a deployment checklist. However, it could better explain how variables, scripts, and policies interrelate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite low schema coverage (30%), the description adds value by listing supported variable types, which aids the 'variables' array parameter. However, it does not describe other simple parameters (name, short_description, etc.) beyond what the schema provides, nor does it cover all 10 parameters in detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a 'complete Service Catalog item definition' with variables, scripts, and UI policies. It uses a specific verb ('generate') and resource ('catalog item definition'), distinguishing it from siblings like 'clone_catalog_item' (clone) and 'get_catalog_item' (read).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating a new catalog item with custom components but does not explicitly state when to use vs alternatives (e.g., clone vs fresh creation). No prerequisites or exclusions are mentioned, leaving guidance to be inferred from the tool 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?
No annotations provided, so description carries full burden. Describes registering a webhook and generating JSON, with loop-prevention mention. Lacks details on side effects, idempotency, permissions, or error handling. Adequate 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Bullet list clearly separates actions, front-loaded with main purpose. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers creation steps and prerequisite, but lacks output format details (e.g., returned data structure). With no output schema, more description of return values would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds minimal extra: notes plan comes from 'design_integration', but does not enrich beyond schema for inbound_url or webhook_secret.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it creates Jira-side artifacts for bidirectional integration, listing three specific artifacts (webhook, automation rule JSON, instructions). It distinguishes from siblings like 'build_jira_automation' and other platform-specific integration tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states it requires the plan from 'design_integration', providing a prerequisite. Does not explicitly exclude alternatives or state when not to use, but context makes 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?
Discloses result limit (25 matches) and search scope (name/label). No annotations provided, so description carries burden; however, it is read-only by nature and no destructive info needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, no fluff, front-loaded with purpose and key detail (result limit). Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, covers purpose and result limit. Lacks output format or pagination info, but acceptable given no output schema and tool simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description reinforces the keyword parameter with 'name or label' clarification, but adds no new constraints or format details beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'search' and specific resource 'ServiceNow tables' with details on how (by keyword in name or label). Distinguishes from siblings like explore_table and suggest_target_table by focusing on keyword search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. Usage is implied but not contrasted with alternatives like explore_table or suggest_target_table.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
In the absence of annotations, the description indicates the tool returns up to 20 matches and includes sys_ids, implying it is a read operation. However, it does not explicitly state non-destructiveness, pagination behavior, or handling of no results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no extraneous information. The most important information (what it searches, return value) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with two parameters and no output schema, the description covers the search criteria, return value, and limit. It could mention behavior for no results or exceeding 20 matches, but is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (keyword described, limit not). The description adds value by clarifying that keyword can search name, ID, or description, and implies the limit parameter through 'up to 20 matches', but does not fully explain limit's behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool searches for Service Portal widgets by name, ID, or keyword and returns up to 20 matches with sys_ids. Distinguishes from sibling tools like clone_widget and update_widget, which 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use the tool (searching widgets by various criteria) but does not mention when not to use it or suggest alternative tools. Provides clear 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?
No annotations are provided, so description carries full burden. It states the tool does not touch ServiceNow via API and produces a human guide. It is transparent about non-destructive behavior, but could mention more details like output format or limitations. Adequate 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: first states purpose, second clarifies non-API behavior, third details guide content. Front-loaded and no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (nested objects, no output schema), description covers purpose, usage, and output. It could specify the guide's format or error handling, but is mostly complete for this tool's straightforward purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter descriptions. The tool description adds context about flow_analysis coming from analysis tools, but does not significantly enhance schema 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a step-by-step guide for migrating Salesforce or Jira flows to ServiceNow Workflow Studio. It specifies the verb 'generates', the resource 'guide', and the context. It also distinguishes from siblings like analyze_flow by stating it should be called after analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this after analyze_flow or analyze_jira_automation', giving clear sequencing. Also clarifies it does not touch the API, implying it's for human guidance. Lacks explicit alternatives but provides enough 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It transparently states that the tool retrieves all ACL rules (including field-level), indicating a read-only operation. However, it does not disclose potential permission requirements, or whether the result set could be large and require 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, and contains no 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/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (one parameter, no output schema), the description is reasonably complete. It explains what is returned (all ACL rules including field-level), which is sufficient for context. A minor improvement would be to mention that it returns a list of rules, but overall it's adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'table' has a description in the schema ('Table name'), and the tool description adds no additional meaning beyond that. Since schema coverage is 100%, the baseline of 3 is appropriate; the description does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'ACL rules for a ServiceNow table', including the scope 'including field-level ACLs'. This distinguishes it from sibling tools like 'validate_target_acl' and 'explore_table', which serve 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (retrieving ACL rules) but provides no explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it. The mention of 'field-level ACLs' hints at granularity, but no exclusions or alternative tool names are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool lists active flows and flags Screen Flows as manual-only, but it does not explicitly confirm that the operation is read-only or has no side effects. For a listing tool, this is adequate but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of three short sentences. It front-loads the core purpose, then adds usage guidance and a special note. Every sentence adds value, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description covers the essential information: what it lists, why to use it, and a special behavioral note (Screen Flows flagged). It is nearly complete, though it could optionally mention the expected return format (e.g., list of flow names with types). However, for a simple listing tool, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters (0 parameters, 100% schema coverage). Since there are no parameters to describe, the description adds no parameter information. Baseline 3 is appropriate as the schema already covers everything.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all active Salesforce flows with their types'), specifies the resource ('Salesforce flows'), and includes a scope ('active'). The note about Screen Flows further distinguishes the tool's output. It is specific and helps the agent understand exactly what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool: 'Use this to show the user what flows are available before asking which to migrate.' This provides a clear usage context. However, it does not mention when not to use it or suggest alternative tools like analyze_flow for deeper analysis, which slightly limits 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?
No annotations provided, so description carries full burden. It describes a read-only report generation (returns verdict, no mention of data modification). It does not mention permissions, rate limits, or detailed behavior when inputs are invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two paragraphs: first states purpose and scope, second gives usage and output. Every sentence adds value; no fluff. Well structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, 7 required, and no output schema, the description covers overall process and output. It mentions combining validate tool with reconciliation and returning pass/fail verdict. Could specify what 'deep reconciliation' entails, but adequate for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 78%, so many parameters have descriptions. Description adds context like 'three-layer field mapping' but does not elaborate on less-documented parameters (transform_rules, date_fields). Overall, parameter meanings are clear from names and schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Generate a complete end-to-end migration test report' covering three layers. It specifies the tool combines existing validate tool with deep reconciliation. The purpose is distinct from siblings like pre_migration_check or run_full_migration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly says 'Use this after a test migration of 5–50 records before running the full migration.' This provides clear context. It implies this tool is for intermediate validation, though it does not list 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?
No annotations are provided, so the description carries the full burden. It mentions that the tool returns a pass/fail report with blocking issues and warnings, and lists the checks performed. However, it does not disclose side effects (though likely none), permissions, or rate limits, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the purpose, uses bullet points for clarity, and includes a clear usage directive. Every sentence adds value without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (4 parameters, no output schema, no annotations), the description is largely complete. It explains what the tool does, what it returns, and when to use it. There is slight ambiguity about whether validation runs against the table itself or the sample records, but overall context is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with descriptions (100% coverage). The tool's description does not add significant new meaning beyond listing the checks, which relate to the parameters but do not detail syntax or usage. Baseline of 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs pre-migration validation checks against a target ServiceNow table, listing specific checks (picklist, reference integrity, required fields, business rules). It distinguishes from sibling migration tools by explicitly stating 'Always call this before run_migration.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance with 'Always call this before run_migration,' indicating when to use it. However, it does not explicitly state when not to use it or when alternatives might be preferable, slightly limiting its completeness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the PATCH nature and return of updated record, but lacks details on auth requirements, error handling (e.g., missing sys_id), and idempotency. Adequate but could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one definitive sentence plus three clear examples. Every element adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (4 params, no output schema) and the detailed examples, the description covers core usage well. Missing error behavior or prerequisites, but overall complete for a standard update operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage; the description adds examples for table, sys_id, fields but does not explain the optional return_fields or the structure of the fields object beyond examples. No enhancement over schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb (update), resource (ServiceNow record), and method (PATCH partial update). It distinguishes from sibling tools like sn_create, sn_delete, sn_read by specifying that it updates an existing record by sys_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Examples show typical usage for updating an incident, sys_user, and sc_task, but no explicit guidance on when to use vs alternatives or when not to use. The context is clear from the name and description, but excluding contraindications lowers the score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses key behaviors: mapping stored in sys_property record, tool updates that property, returns new active mapping, and changes take effect on next sync. This is sufficient for a non-destructive update tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with purpose, then provides usage and behavioral details. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and moderate complexity, the description covers purpose, usage, and key behavioral details. It is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions for all parameters (prefix, field_mappings, merge). The tool description does not add additional meaning beyond the schema, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates field mapping configuration for an existing integration without recreating artifacts. It uses specific verb and resource, but does not explicitly distinguish from sibling tools like 'design_integration' or 'create_jira_integration_artifacts', though the purpose 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions use cases: adding new fields, removing fields, or correcting mapping mistakes. It does not specify when not to use or provide alternative tools, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states 'verifies' but does not disclose whether the tool has side effects, what happens on success/failure, or if it returns a result. Moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded action and usage advice; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple validation tool, but lacks details on return values or behavior after verification. Without output schema, the agent may be unsure how to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter sn_table is not described in the description; schema coverage is 0%. The parameter's purpose (target table) is implied but no format, examples, or constraints are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool verifies ServiceNow integration user permissions on a target table, specifying verb and resource. It distinguishes from siblings by focusing on ACL validation and provides usage 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit instruction to call before build_artifacts to catch permission problems early, giving clear when-to-use and rationale.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral aspects. It describes the action as fetching and parsing metadata, implying a read operation, but it does not explicitly state it is non-destructive, nor does it mention permissions, rate limits, or error conditions. The description is adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each serving a clear purpose: (1) state the tool's action and result, (2) specify the output structure, (3) provide usage guidance. It is front-loaded with the core purpose and avoids redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers the main functionality and provides some contextual flow. However, it lacks details on preconditions, error handling, and idempotency. For a tool fetching complex metadata, more completeness would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with parameters already well-described in the schema (flow_api_name and sn_table). The description adds no additional meaning beyond stating the tool operates on a Salesforce flow and a ServiceNow table, which is already implied. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Fetch and parse a Salesforce flow's full metadata' and 'Returns structured breakdown of trigger, variables, and elements'. It clearly distinguishes itself from sibling analysis tools by specifying the target (Salesforce flow) and the scope (full metadata).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear workflow instructions: 'After calling, present the analysis to the user and ask the clarifying questions required for Checkpoint F1. Only call build_flow after user confirms the understanding is correct.' This tells when to use the tool in relation to other steps and the sibling build_flow.
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 no annotations provided, the description carries the full burden. It discloses that the tool generates code as strings (not deploying), lists the specific artifacts created, and mentions a step-by-step deployment instruction. This provides good behavioral insight, though side effects or additional constraints are not explicitly covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a bullet list outlining five specific artifacts, a note about manual deployment, and a clear prerequisite. Every sentence is informative and earned its place, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple artifacts generated), no output schema, and no annotations, the description should clarify the return value format. It explains what is generated but not how it is returned (e.g., a single string, multiple strings, or a structured object). This is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters (plan, target_url) are described in the input schema with 100% coverage. The description reiterates the plan's origin and target_url's use in Named Credential, adding minimal new meaning beyond the schema descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates Salesforce-side code and configuration for a bidirectional integration, listing specific artifacts (Named Credential XML, Apex classes, etc.), which distinguishes it from sibling tools for other platforms like Jira or ServiceNow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes the prerequisite of having an integration plan from design_integration and explains that the generated Apex code must be manually deployed. However, it does not explicitly state when to use this tool versus alternatives, though the sibling context implies it's for Salesforce.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the approval workflow and plan contents but does not mention side effects, auth requirements, or whether the plan is stored. Lacks details on mutation or persistence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with main purpose, uses bullet points for plan contents, and clear flow instructions. No wasted sentences, well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should explain return format. It describes the plan's contents but not how the output is structured (e.g., object fields). Agent needs to know what to present to user. Also lacks runtime details or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with param descriptions. The description adds context: analysis is from analyze_for_testing, and priority enum is explained with 'all=full suite | critical=CRITICAL only | smoke=first 3 tests', which goes beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a detailed expert test plan from an analysis result, specifying the resource and verb. It lists plan contents (CRITICAL, MAJOR, MINOR tests, scripts, runtime) and distinguishes the tool from siblings like generate_atf_tests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly marks this as the approval step, instructs to present the plan and ask for user approval before calling run_approved_tests. Provides clear context for when to use, though no explicit when-not or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility. It thoroughly enumerates all output categories (table metadata, fields, business rules, client scripts, ACLs, relationships, hierarchy, counts), leaving no ambiguity about the tool's read-only exploratory 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a bold lead sentence, bulleted list of returns, and a concluding usage note. It is appropriately detailed for a schema discovery tool, though the bullet list could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's two simple parameters and no output schema, the description provides exhaustive context about what the tool returns and when to use it. An agent receiving this description would have complete understanding of the tool's function and outputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds example values for 'table' but otherwise does not enrich parameter meanings beyond the schema. Acceptable but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Full schema discovery for a ServiceNow table' and lists specific metadata returned. It distinguishes from siblings like discover_schema or find_table by focusing on comprehensive context, 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Use this before writing a BR or Client Script to understand the full context.' This provides a clear use case, though it does not state when not to use it or mention alternative tools for partial discovery.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. The description suggests a read-only operation (listing overrides) but does not explicitly state that it is non-destructive or safe. It does not discuss permissions, rate limits, or return format. The lack of behavioral details is acceptable for a simple list tool, but could be improved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear main sentence followed by two brief usage examples. It is front-loaded with the primary action and uses no unnecessary words. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (3 parameters, no output schema), the description is reasonably complete. However, it does not describe the return value or output structure, which could be helpful for an agent. The examples partially compensate, but some behavioral context (e.g., whether results are paginated) is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for two of three parameters (67% coverage). The description adds value by showing example combinations of parameters (e.g., table='incident', field='priority', override_type='mandatory'), which helps agents understand how to use them together. This exceeds 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List all dictionary overrides on a table, or find overrides for a specific field.' It uses specific verbs and resource, and distinguishes itself from sibling tools like create_dictionary_override and delete_dictionary_override by emphasizing auditing and checking before creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises when to use the tool: 'Use this to audit what a child table has customised vs its parent, or to check whether an override already exists before creating one.' It provides examples for different query combinations. While it doesn't explicitly state when not to use it, the context is clear given the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that description text is plain text wrapped in ADF, a behavioral detail. However, it does not reveal permissions needed, idempotency, side effects, or error handling. Since no annotations are provided, the description carries the full burden and falls short of comprehensive transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a concise opening sentence, a bullet list of resource_type options, and two concrete examples. Every sentence serves a purpose, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the most common use cases and resource types, but omits explanations for parameters like extra_fields, parent_key, and component_lead. No output schema is provided, and the description does not describe return values, leaving gaps for complex scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 87% schema coverage, the baseline is 3. The description adds value by explaining the resource_type enum options and showing a complete issue creation example, which clarifies how parameters like project_key, summary, and priority should be used together.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create any Jira resource' and enumerates specific resource types (issue, comment, subtask, component, version) with examples, making the tool's purpose explicit and distinct from sibling tools like jira_read or jira_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on resource_type options and usage patterns via examples (issue and comment), but does not explicitly exclude cases when to use alternative creation tools like jira_create_group. However, the listed resource types implicitly define the scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. Lists read-only behavior (listing), but doesn't mention permissions, rate limits, or other side effects. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. Purpose stated first, then usage context. Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description doesn't specify return fields or format. For a list tool, this leaves the agent guessing about available data. Partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters to document, and schema coverage is 100%. Baseline 4 for zero params applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'in-progress Update Sets', clearly stating the tool's purpose. It distinguishes from creation tools like 'create_update_set' by implying this is for reuse.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using before creating a new update set, with reasoning about reuse and migration continuity. Doesn't list when not to use or alternatives, but guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry full behavioral disclosure. It explains the PATCH behavior (only provided fields changed) and the return value ({updated: true}). However, it omits critical details like error responses, required permissions, or record existence handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence summarizing the action, three illustrative examples, and a clear return value. Every element is necessary and front-loaded, with no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of output schema and annotations, the description provides the essential usage pattern and return format. It lacks details on validation, errors, or side effects, but covers the core functionality adequately for a straightforward update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions already cover the parameters (object API name, record Id, field-value pairs). The description adds value through concrete examples showing typical usage with different data types, and clarifies the PATCH semantics (only provided fields changed), which enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a Salesforce record by Id') and the HTTP method (PATCH), distinguishing it from sibling tools like sf_create (create) and sf_delete (delete). Examples further reinforce the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use: updating existing records by Id, with partial field changes. It does not explicitly exclude creation or other actions, but the context from sibling names and the verb 'Update' make usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that it opens a log file and records subsequent migrations, but does not specify side effects like file overwrite behavior, permissions required, or whether it is safe to call multiple times.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary action, followed by what gets recorded, and ends with clear usage guidance. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 optional parameters, no output schema, no nested objects), the description covers the purpose, recording behavior, and usage timing adequately. No missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters. The tool description adds no additional meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Open an audit trail log file') and the resource ('for this migration session'), and distinguishes it from siblings by specifying it is a one-time setup step for production migrations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to call this once at the start of any production migration, providing clear usage context. However, it does not mention when not to use it or any alternatives, though the sibling list includes related but different 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?
No annotations are provided, so the description carries full burden. It describes the checks (comparing counts, detecting duplicates) and implies a read-only operation ('verify'), but it does not explicitly state that the tool does not modify data, nor does it mention required permissions or potential side effects. It adds some transparency but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear header, bulleted list of checks, and usage guidance. It is concise without being terse, and every sentence contributes value. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about the output format. While it lists the checks performed, it does not explain what the tool returns (e.g., a report, a table, a JSON object). With no output schema, this is a notable gap. However, the tool context is otherwise complete for the verification task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 6 parameters with descriptions (100% coverage). The description adds meaning beyond the schema by explaining how parameters are used in the verification flow (e.g., 'project_field for scoped queries'). This helps understand parameter interactions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: verifying record counts across three layers of a migration (source, staging, target). It lists specific checks, making the action very explicit. This distinguishes it from sibling tools like 'analyze_migration_for_testing' or 'reconcile_migration' by focusing solely on count verification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'after a full migration to confirm data integrity' and 'after a test migration to see how many records were actually moved'. This provides clear context, though it does not mention alternative tools or explicitly 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?
With no annotations, the description fully explains the tool's behavior: it returns portal metadata, pages, widgets, usage counts, and theme details. It implies a read-only operation and provides a detailed output list, though it does not explicitly state side effects or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct with no wasted words: it starts with the core action, then parameter detail, then a bullet-style list of returns, and ends with a usage tip. Ideal front-loading and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists all major return categories, compensating for the lack of output schema. It covers metadata, pages, widgets, usage counts, and theme. However, it omits potential prerequisites (e.g., portal existence) and does not mention error cases or data freshness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 100% with a description for 'portal_id'. The description adds that the value can be a URL suffix or sys_id, which aligns with the schema but does not add meaningful new semantics beyond the schema's own description. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it analyzes a complete Service Portal, listing specific components (pages, widgets, theme, usage counts), and distinguishes from sibling 'analyze_*' tools which target different domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly advises using the tool before starting portal development to understand existing artifacts, providing a clear context of use. It does not explicitly exclude scenarios or list alternatives, but the context is strong.
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?
Discloses that credentials are held in memory only, never stored or logged, and explains OAuth prerequisites. No annotation provided, so description carries the burden well. Minor omission on error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for when-to-call and how-to-ask. Slightly verbose but each part earns its place. Could be trimmed, but still clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description does not explain what the tool returns (e.g., success confirmation). Lacks information on rate limits or failure modes. Adequate but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The 'HOW TO ASK THE USER' section adds detailed instructions for obtaining each parameter (e.g., Connected App setup), going beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Connect to a Salesforce org in one step,' which is a specific verb+resource. The name and content distinguish it from sibling tools like connect_jira and connect_servicenow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'WHEN TO CALL' section provides clear context: at session start or when get_config shows salesforce.configured = false. Does not explicitly state when not to use, but the context suffices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions output is 'HTML safe for SN fields' and auto-detection, but does not disclose error handling, size limits, or behavior with unsupported formats. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, followed by supported formats and return info. No redundant words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description briefly notes return type (converted HTML). Parameters are well covered. Minor gap: does not specify output structure (e.g., array of converted values). Still sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds value by explaining hint="auto" for auto-detection and clarifying that 'value' can be ADF object, HTML string, or plain text, going beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool converts rich text to ServiceNow-compatible HTML, specifies supported formats (Jira ADF, Salesforce HTML, plain text), and mentions auto-detection via hint. This distinguishes it from sibling tools which are unrelated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use when needing to convert rich text for ServiceNow, but does not explicitly state when not to use or provide alternatives. Among many siblings, none directly compete, so context is clear but lacks exclusion 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?
Since no annotations are provided, the description carries full burden. It discloses that deletion is immediate, requires confirmation, and gives an example of behavioral change (mandatory field becoming optional). Does not mention auth needs or rate limits but covers key behavioral aspects 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is three sentences with clear structure: purpose, safety note, prerequisite. Every sentence provides value. No fluff. Front-loaded with primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and no annotations, the description covers purpose, safety, and prerequisite. Does not explain return values or error cases, but for a straightforward delete operation, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. The description mentions 'Find the sys_id first' which is not a parameter in the schema (tool uses table and field instead). This minor inconsistency may confuse agents but does not detract from parameter meaning. Description adds little beyond schema explanations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool deletes a dictionary override and explains the effect (restoring parent defaults). The verb 'delete' and resource 'dictionary override' are specific. Sibling tools 'create_dictionary_override' and 'get_dictionary_overrides' are distinct, so purpose is well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides explicit safety requirement (confirm=true) and prerequisite (find sys_id with get_dictionary_overrides). It implies the tool is used to revert overrides but does not explicitly state when to avoid using it or compare to alternatives. Still clear enough for practical 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?
No annotations are provided, so the description carries the full burden. It explains the tool produces a plan and lists what the plan includes, but it does not disclose any behavioral traits like whether it modifies existing data, requires specific permissions, or is a read-only operation. The description implies analysis and planning without side effects, but this is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with bullet points, and front-loaded with the core purpose. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, nested objects, no output schema), the description is quite complete. It explains the plan's content and how to use it with sibling tools. However, it lacks details on the return format or structure of the plan, which would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (89%), so the baseline is 3. The description adds overall context about the plan's content but does not add significant meaning beyond what the schema provides for individual parameters. It lists artifact types but not parameter-specific details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Analyse a user's bidirectional integration requirement and produce a complete, structured integration plan.' It lists supported platform combinations and enumerates artifacts. It distinguishes from siblings by stating 'Call this FIRST before any create_integration_* tool.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool: 'Call this FIRST before any create_integration_* tool. Pass the result to the other tools to actually create the artifacts.' This provides clear ordering and 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?
No annotations are provided. The description does not disclose side effects, output format, or potential constraints (e.g., rate limits, caching). However, 'explain' is inherently safe and read-only. The list of topics adds context but doesn't fully compensate for missing behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence plus a bulleted list. It is front-loaded with the purpose and uses efficient structure. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, single-parameter tool with no output schema, the description covers the purpose and scope adequately. It could mention that the output is a textual explanation with examples, but the lack of output schema and low complexity make the current level acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema defines 'topic' briefly, but the description enriches it with a concrete list of acceptable topics. This helps the agent select appropriate values and understand the scope, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('explain') and the resource ('ServiceNow API, class, or method'). It differentiates from sibling tools by focusing on explanation rather than analysis or generation, and the list of topics further clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly defines when to use this tool (when needing an explanation of ServiceNow concepts). It provides a list of example topics, but does not explicitly state when not to use it or mention alternatives, though no direct competitors exist among 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?
No annotations provided, but the description clearly states the tool returns ATF test suite JSON with steps and deploy instructions, implying no side effects (generation only). No contradictions or missing behavioral traits for a generation tool of this 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a one-line purpose followed by a bulleted list of targets. No extraneous words, front-loaded, and well-structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite good purpose clarity, the description lacks detail on many parameters (e.g., trigger_conditions, field_changes, expected_outcomes), the exact format of the returned JSON, or deployment instructions. For a complex tool with 14 parameters and nested objects, this is insufficient 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14% (2/14 parameters documented). The description adds value by explaining target_type meanings and conditional requirement for 'table', but omits semantics for many parameters like trigger_conditions, field_changes, expected_outcomes, methods, etc. Partially compensates but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates ATF test cases for ServiceNow artifacts, lists five specific target types with their test generation focus (e.g., 'business_rule — positive, negative, and field-change trigger tests'), and distinguishes itself from sibling tools like 'analyze_for_testing' or 'create_test_plan' which are more analytical or planning-oriented.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on what tests each target type generates, implying usage scenarios (e.g., business rule tests for trigger conditions), but does not explicitly state when to use this tool versus alternatives like 'analyze_for_testing' or indicate when not to use it. This is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the output includes 'ready-to-deploy script code plus best-practice checklist and deploy field values,' which is transparent about what the tool returns. It does not mention any side effects, which are minimal for a generation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, starting with the overall purpose and then listing supported types in a clear, bullet-like format. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (22 parameters) and the absence of an output schema, the description covers the main aspects: what the tool does, what it returns, and the different script types. However, it omits details on many parameters, which lessens completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (32%), and the description does not detail individual parameters beyond listing the 'type' examples. It adds meaning to the 'type' parameter but does not compensate for the many other parameters (e.g., table, logic, condition). The description adds some context but not enough given the parameter count.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates production-ready ServiceNow scripts with best practices, and lists eight distinct script types. This is specific and distinguishes it from sibling tools like 'review_script' or 'run_background_script'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use each script type via the list and brief descriptions. However, it does not explicitly state when not to use this tool or mention alternatives, so some guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It does so by listing three read-oriented queries (correlation, retry/error, recent sync activity) and the phrase 'Check the health' strongly implies a read-only operation with no side effects. While it doesn't explicitly state non-destructiveness, the transparency is sufficient given the read-only 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a two-sentence introduction followed by a bulleted list of three items, plus a final usage sentence. Every sentence adds value without redundancy. The bullet format aids quick scanning, and the total word count is low for the information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 parameters, no output schema, no annotations), the description covers the essential aspects: what the tool checks, the parameters, and when to use it. It does not describe the return format, but the absence of an output schema means the description is not expected to detail that. A minor gap is not specifying that results are returned as a JSON object, but overall it's sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for both parameters: 'prefix' and 'last_n_errors'. The description adds context by naming the tables queried and mentioning 'last N records synced', but does not directly map to the 'last_n_errors' parameter (which controls errors, not all sync records). This slight disconnect prevents a higher score, but the schema already provides clear meanings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Check' and resource 'health of a running bidirectional integration', clearly listing three query areas (correlation table, retry/error table, recent sync activity). This is distinct from sibling tools like 'health_check_instance' which checks instance-level health, and 'monitor_import_set_progress' which monitors import sets. The purpose is unambiguous and well-scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use this to monitor the integration after it goes live', providing clear usage context. However, it does not mention situations where this tool should not be used (e.g., before deployment) or alternative tools for related tasks (e.g., 'diagnose_issue' for troubleshooting failures). Still, the guidance is direct and helpful.
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 no annotations, the description carries full burden. It discloses the process: fetching recent N staging records, looking up target records via sys_target_sys_id, and comparing mapped fields. Return types (per-record diffs, per-field accuracy, missing targets) are mentioned. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three well-structured sentences. Purpose is stated first, followed by context, then details on behavior and output. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested objects, multiple parameters, no output schema), the description provides a good overview of the tool's function and output. It explains the comparison process and what is returned, though it could elaborate on how transform_rules and date_fields affect the comparison.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%. The description adds value by explaining that sample_size controls how many records are checked and that field_mappings define the fields to compare. It also introduces the concept of sys_target_sys_id, which is not a parameter but aids understanding. Missing explicit elaboration on transform_rules and date_fields, but overall adds meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: comparing staging and target tables to verify transform map correctness. It also explains its role as the staging-to-target leg of a three-layer quality check, distinguishing it from sibling tools like reconcile_migration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after a transform map to check correctness, but does not explicitly state when to use this tool versus alternatives. No exclusions or alternative tools are mentioned, leaving the agent to infer 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?
With no annotations, the description provides key behavioral details: automatic dependency ordering for Jira, paginated bulk for Salesforce, and immediate error stop with reporting. It does not cover whether the operation is destructive, idempotent, or auth requirements, but the core behaviors are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is five sentences, each serving a purpose: overall function, two platform-specific behaviors, prerequisite (checkpoint approval), and error handling. No fluff, well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a multistage full migration and no output schema, the description covers the essential workflow (phases, platforms, error handling) and constraints (checkpoint approval). It could mention prerequisites like mapping configuration, but is largely complete for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 5 parameters (4 required) with 60% schema description coverage. The description does not elaborate on parameters beyond implying 'platform' and 'object_name'. Without parameter detail, agents must rely on schema descriptions alone, which are incomplete for the remaining 2 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Migrate ALL records from source to ServiceNow.' It specifies platform-specific behaviors (Jira dependency ordering, Salesforce paginated bulk) and distinguishes itself as a full migration phase (Phase 6) among siblings like run_test_migration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly requires 'explicit user approval at Checkpoint 4' before calling, establishing a clear precondition. It also notes error handling ('Stops immediately on any error and reports'). However, it does not explicitly state when not to use it (e.g., prefer run_test_migration for testing) 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?
No annotations are provided, so the description carries the full burden. It explains the three read modes and their parameters but does not explicitly state that the tool is read-only, nor does it disclose potential side effects, required permissions, API limits, or error handling behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured, using bullet points to separate read_type options and providing clear examples. Every sentence adds value, and the format is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (6 parameters, 1 required, no output schema), the description covers the core functionality well. It explains all read modes and their dependencies. However, it lacks information about the return format (e.g., JSON structure) and any implicit constraints (e.g., connection prerequisites).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), and the description adds significant value beyond the schema by providing concrete examples for each read_type, showing how to combine parameters like id, fields, soql, and limit. It clarifies the purpose of each parameter in context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read Salesforce records' and enumerates three distinct read_type options (by_id, query, describe) with examples. This distinguishes it from sibling tools that perform create, update, delete, or other operations on Salesforce or other platforms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each read_type, including required parameters for each mode and examples. However, it does not contrast this tool with other read tools (e.g., jira_read, sn_read) or specify scenarios where this tool 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It mentions using the Table API, creating a record, and returning the created record with sys_id. It does not detail error handling or rate limits, but for a simple create operation, it is adequately transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, including three clear examples without unnecessary text. It is well-structured with examples on separate lines, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explicitly states the return value ('Returns the created record including its sys_id'), which is sufficient. All key aspects of the tool's behavior are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds examples that illustrate parameter usage but does not significantly augment the schema meaning. Baseline 3 due to high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a record in any ServiceNow table via the Table API'. Verb and resource are specific, and it effectively distinguishes from sibling tools like sn_read, sn_update, sn_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples for different tables (incident, sc_task, sys_user, custom), implying usage contexts. However, it does not explicitly state when not to use or compare to alternatives, but the purpose is clear enough to guide 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?
With no annotations, the description must fully disclose behavior. It states the tool creates a group and optionally assigns members/roles/manager, and returns the sys_id along with assignment results. It lacks details on prerequisites (e.g., manager user must exist), failure modes, or side effects (e.g., notifications triggered). This is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a single sentence explaining the core action, followed by a brief bullet list of use cases, then a clear note on return values. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (10 parameters, no output schema), the description covers the return format and primary actions. However, it omits error scenarios and permission requirements, which would be helpful for a comprehensive understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 80% of parameters with descriptions, and the description adds a useful hint for the 'name' field ('should be clear and unique'). This enhances understanding beyond the schema, especially for a 10-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a ServiceNow group' and lists optional assignments, distinguishing it from sibling tools like sn_create (generic record creation) and sn_manage_group_members (member-only management). The verb 'Create' is specific and the resource 'ServiceNow group' is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists use cases for groups (assignment, approval, notifications, ACLs), providing context for when to create groups. However, it does not explicitly contrast with sibling tools like sn_update (for modifying existing groups) or sn_manage_group_members (for post-creation member changes), leaving room for ambiguity.
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 no annotations, the description carries full burden and discloses key behaviors: auto-generating user_name, setting active=true, assigning roles/groups in one call, and return value (sys_id plus links). However, it does not mention prerequisites (e.g., roles must exist) or safety considerations like 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a clear purpose sentence, a bullet list of key behaviors, and a return statement. Every sentence adds value without redundancy, appropriate for 19 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 19 parameters including a nested object, the description covers the main use case, common pitfalls, and return value. It lacks explicit guidance on extra_fields usage or prerequisites for roles/groups, but schema descriptions fill most gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 95% (high), so baseline is 3. The description echoes schema info (auto-generation, defaults) but adds little new meaning beyond emphasizing 'commonly missed fields'. It does not detail format expectations for roles/groups beyond the schema's array of strings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create', the resource 'ServiceNow user (sys_user)', and the scope 'with all standard fields, optional roles, and optional group membership'. It differentiates from sibling tools like sn_create (generic) and sn_create_group by specifying the exact record type and included features.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for using the tool (creating a user with optional roles/groups) but does not explicitly mention when not to use it or name alternatives. It implies comprehensive coverage but lacks exclusions like 'if you only need a user without roles, consider sn_create'.
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 no annotations provided, the description carries the full burden of behavioral disclosure. It clearly communicates the irreversible nature of the deletion and the necessity of explicit confirmation. It also mentions the preview mode. However, it does not describe error handling or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose, a safety warning, and two example calls. Every sentence earns its place with no superfluous text. It is front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with three well-documented parameters and no output schema, the description covers usage and safety adequately. It could mention what the tool returns on success or failure, but the core functionality is fully described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. The description adds examples but no new semantic information beyond the schema. The baseline of 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'a ServiceNow record', specifying the method 'by sys_id'. Examples further clarify the exact usage. This tool is distinct from siblings like sn_create, sn_read, and sn_update, as it focuses exclusively on deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly requires confirm=true for actual deletion and warns that the action cannot be undone. It also explains how to preview without deleting (confirm=false). However, it does not explicitly state when not to use this tool or list alternatives (e.g., for updates).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes behavior for different input combinations and includes examples, but lacks details on return format, pagination, error handling, or any side effects. The default limit is mentioned but not bounds 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and examples. Every sentence adds value, and it is front-loaded with the core purpose. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, no output schema), the description covers all key use cases and parameter interactions. It is missing details on return format and error handling, but is otherwise comprehensive and complete enough 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds value by explaining the interplay between sys_id, query, and leaving both blank, and includes concrete examples showing how to combine parameters. This goes beyond the schema's individual field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read one or many records from any ServiceNow table' and distinguishes three use cases (single record by sys_id, multiple by query, first N). This differentiates it from sibling tools like sn_create, sn_update, sn_delete, and fetch_sn_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each parameter combination (sys_id for single, query for multiple, both blank for first N). It implicitly contrasts with write tools but does not explicitly state when not to use this tool or provide 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?
With no annotations, the description carries full burden. It discloses that the plan is presented for approval and that run_approved_tests must be called to execute. It does not mention side effects or safety, but the workflow is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a brief purpose, a note about the approval flow, and clear usage examples. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a composite, the description explains the flow and inputs well. No output schema exists, and the description does not detail the test plan structure, but for the intended use (generating a plan for approval) it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (per context) and the description adds some context (e.g., 'code or file content' aligns with code param, artifact type examples match enum). However, it doesn't significantly deepen understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: a one-shot shortcut that combines analyze_for_testing and create_test_plan to generate a full expert test plan from code. It distinguishes itself from siblings by being a composite operation and explicitly mentions it does not run tests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: when a user says 'test this code', uploads a .js file, or provides a script include, business rule, or REST script. It implies alternatives (separate analyze and plan tools) but doesn't explicitly state when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it returns a PATCH payload (not directly updating the widget), which is a key behavioral trait. However, no annotations are provided, and the description does not cover authentication needs, error handling, or other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three sentences with no redundant information. Every sentence adds necessary context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low parameter count (2), high schema coverage, and no output schema, the description adequately covers the tool's purpose, usage, and return value. It mentions the endpoint, updatable sections, and that the result is a PATCH payload.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by listing the updatable sections (template, css, client_script, etc.) and explicitly stating that only desired sections should be included. This adds meaning beyond the schema property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'update', the resource 'widget', and specifies the action: 'Build a PATCH payload to update specific sections'. This differentiates it from sibling tools like create_widget or clone_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance: 'Provide the widget sys_id and only the sections you want to change.' It implies when to use (partial updates) but does not explicitly mention when not to use or provide 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?
No annotations provided, so description carries full burden. It discloses that credentials are held in memory only and never stored or logged, plus steps after call. Could mention connection failure handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with WHEN TO CALL and HOW TO ASK THE USER sections. Every sentence provides value, no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and description doesn't explain what the tool returns (e.g., success indicator). It instructs to 'confirm connection' but doesn't specify tool's output. Lacks completeness for a connection tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description adds context about how to ask the user but doesn't significantly enhance meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool connects to a Jira Cloud instance in one step. It distinguishes from siblings like connect_salesforce and connect_servicenow by specifying Jira.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call (start of session or when jira.configured is false) and provides a detailed script for asking the user for credentials.
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 no annotations, the description carries full burden. It details what data is collected (source schema, SN schema, approved mappings, etc.) and that it's ready for rendering. It implies a read-only operation and mentions dependency on prior steps, but lacks explicit side-effect disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, content list, usage order. No wasted words, front-loaded with key information, and well-structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, nested objects, no output schema), the description provides a high-level overview but lacks detailed return structure. Agent needs the output format to pass to docx skill; the description lists components but not exact fields. Error handling and prerequisites beyond ordering are absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (high), so baseline is 3. The description adds value by mapping parameters to output components (e.g., 'artifact sys_ids' corresponds to artifacts parameter, 'migration stats if available' to migration_stats). It contextualizes the required parameters without duplicating schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Collects all data needed to produce a customer-facing field mapping sign-off report' and specifies the output is structured content ready for rendering. It distinguishes from siblings by indicating it should be called after discover_schema and optionally after build_artifacts/run_full_migration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this after discover_schema and optionally after build_artifacts / run_full_migration,' providing clear when-to-use guidance. While it doesn't explicitly state when not to use, the context and sibling differentiation imply correct 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?
Without annotations, the description details the checks performed (connectivity, error counts, job success, indexes, etc.) and the output (health score, action list). It is transparent about scope and return, though does not state if any state changes occur (likely read-only).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: an introductory sentence, a bullet list of checks, and a concluding line on output. No redundant words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations or output schema, the description sufficiently covers purpose, inputs (none), checks, and output format. It provides enough context for an AI agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters are defined in the schema, so no additional semantic detail is needed. The description correctly implies no external inputs, achieving baseline clarity for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Run a comprehensive health check' on the 'connected ServiceNow instance', listing specific checks. It distinguishes from sibling tools which are more focused on dependencies, flows, or integrations, not general health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. However, the description implicitly suggests usage for instance health monitoring. There is no mention of alternatives or context for decision.
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 no annotations provided, the description carries full burden. It states that the tool 'Returns a summary of each rule: name, trigger type, number of conditions/actions, enabled state' and provides a post-call instruction. This is adequate for a read-only list operation, though it does not disclose auth needs 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of three concise sentences that are front-loaded: the first states the purpose, the second gives usage context, and the third describes the return format and next step. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although there is no output schema, the description explains exactly what is returned. The tool is simple with one optional parameter documented in the schema. For a list tool used in a migration workflow, the description is complete and provides all necessary information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter 'project_key', and the schema description already explains its meaning. The main description does not add additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Lists all Jira Automation rules visible to the authenticated user.' This is a specific verb+resource combination that clearly indicates the tool's function, and it is distinguishable from sibling tools like analyze_jira_automation and build_jira_automation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this when the user wants to migrate Jira automations to ServiceNow Flow Designer,' providing clear context for when to use the tool. Although it does not mention when not to use it or name alternatives, the context is sufficient given the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It thoroughly explains behavior for Jira (user checks, hierarchy, sequenced plan) and Salesforce (record counts, relationships, owner checks, warnings, order). 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with Jira and Salesforce sections plus usage note. All sentences add value; no redundancy. Front-loaded with primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description hints at outputs (plan, counts, warnings). Covers preconditions and behavior. Could be more explicit about return value format, but adequate given complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters with descriptions (100% coverage). Description repeats basic parameter meaning but does not add significant additional context beyond schema. Baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'analyse', resource 'migration dependencies', and phase 'Phase 3'. It distinguishes from siblings by specifying its place in the workflow (after discover_schema, before build_artifacts) and provides platform-specific detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call after discover_schema and before build_artifacts. Advises on handling missing users. Lacks explicit alternatives or when-not-to-use, but context is clear given sibling tool names.
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 no annotations, the description carries the full burden. It details the operations: fetches all widget sections, applies modifications, and returns a payload with provenance comments. However, it does not disclose error handling, authentication needs, or whether the payload is immediately written.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear purpose sentence, followed by a bullet list of actions, then modifiable fields, and finally the return value. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters (2 required, nested objects) and no output schema, the description covers the core functionality, modifications, and return value. It could mention payload format or validation, but overall is sufficiently complete for a clone operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is about 75% (source_id, new_name, new_id have descriptions; modifications does not). The description adds meaning by listing the specific modifiable fields (template, css, etc.) and explaining the output, compensating for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('clone') and resource ('Service Portal widget'), clearly differentiating from sibling tools like 'create_widget' and 'update_widget'. It explains the workflow: fetching widget sections, applying modifications, and returning a payload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description communicates when to use the tool (cloning an existing widget with optional modifications) and implies alternatives exist via sibling list, but lacks explicit when-not-to-use or exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains the function (captures config changes into a named package) and its role in the migration workflow. However, it does not detail potential side effects, permissions, or error states, though the creation action is inherently non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet complete, front-loaded with the purpose, uses bold for important notes, and provides examples and workflow sequencing without extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 params, no output schema), the description adequately covers purpose, usage sequence, and naming conventions. It could mention return values or confirmation, but it is otherwise well-rounded.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description reinforces the name parameter with examples and the instruction to ask the user, adding some value beyond the schema, but not significantly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool creates a ServiceNow Update Set for capturing migration changes. Differentiates from siblings like list_update_sets and complete_update_set by specifying the role in the workflow (after connect, before build_artifacts).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (before migration setup, after connect, before build_artifacts), when not to (if an existing update set can be reused, use list_update_sets instead), and includes a critical instruction to ask the user for a name. Provides naming examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns all source fields (none skipped) and that it should be followed by user review. It warns about discarding prior suggestions if sn_table changes. However, it does not explicitly state whether the tool is read-only or if it has side effects, nor does it mention authorization needs 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (purpose, workflow, important notes). It is front-loaded with the main purpose. While it is somewhat long, every sentence adds useful information for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, no output schema, no annotations), the description is highly complete. It explains what the tool returns, the workflow to follow, how to handle edge cases (table changes, unmapped fields), and what actions to take after calling it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the workflow and dependencies: sn_table must come from suggest_target_table, platform can be any string, and object_name is the source object. This adds value beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Discover ALL source fields and ServiceNow target fields side by side.' It specifies it returns complete field lists, auto-suggested staging table, and field mapping proposals. This distinguishes it from sibling tools like suggest_target_table, which is referenced in the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: after sn_table is known (via suggest_target_table first if needed), and before build_artifacts. It also states when NOT to use it (if sn_table changes, call again from scratch). Alternatives are mentioned (suggest_target_table).
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 the process (takes manual results and combines with plan to produce report) without mentioning any side effects or modifications. Since no annotations are provided, it carries the full burden and does so adequately, though it does not explicitly state that the operation is non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with three short paragraphs and bullet points for usage. It front-loads the core purpose and avoids unnecessary words, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, no output schema, and nested objects, the description adequately explains the process and what the report contains (score, verdict, recommendations). It could be more explicit about the return format, but it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds context about the parameters (e.g., manual results) but does not provide additional semantic detail 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states it re-generates a structured test report from manual results and the original plan, clearly specifying the resource (test report) and action (re-generate). It also distinguishes from siblings like 'create_test_plan' by focusing on manual results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists three use cases: when tests are MANUAL_REQUIRED, when user ran Fix Scripts manually, and when a clean summary of mixed results is needed. This provides clear context for when to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool loads all SN users/groups into memory, resolves users, and returns a match report. It does not explicitly indicate whether it is read-only or its performance impact, but the main behaviors are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-load the action, then describe output and usage. No wasted words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers the essential aspects: what it does, what it returns, and when to call it. It could mention the heavy load of loading all users/groups, but overall it is sufficiently complete for a preparatory tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by tying the parameters to the resolution process (e.g., 'fallsback user' relates to fallback_user_email) and explaining the output, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: loads ServiceNow users and groups, then resolves source-platform users to sys_ids. This is a specific verb+resource and distinguishes it from sibling migration tools that perform other actions like creating records or running migrations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this before running a migration that has assignee / owner / reporter fields,' which provides clear guidance on when to use. It does not include explicit exclusions or alternatives, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the tool's behavior: sends sample records, checks three layers (source, staging, target), calculates fill rates, and flags data loss. It mentions default sample size. However, it does not explicitly confirm non-destructiveness (though implied) or describe 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet informative, using a clear structure: opening sentence, bullet-like list of report layers, and concluding usage guidance. Every sentence serves a purpose with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, process, output details (three layers, fill rates, flags), and prerequisites. Missing is the exact return format (e.g., data structure) since no output schema exists, but it adequately sets expectations for a migration test report.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 57%, with some parameters undocumented. The description adds context for sample_size (default 5, recommended 5–10) and explains the three-layer report, but does not elaborate on other parameters like filter or staging_table. It adds modest value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a trial run of the migration pipeline on a small sample and produces a detailed quality report. It uses specific verbs and resources, and distinguishes itself from sibling tools like run_full_migration by emphasizing the trial nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit instructions are given: 'Only call this after build_artifacts' and 'Only call run_full_migration after the user reviews this report and explicitly says Approved.' This clearly delineates when to use this tool versus 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?
No annotations are provided, so the description carries full burden. It discloses that the delete is immediate but recoverable for 15 days via Recycle Bin, and mentions preview mode. This sufficiently conveys the destructive nature and recovery mechanism.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at 5 lines, front-loaded with the purpose, and every sentence contributes essential information. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-param required tool with no output schema, the description covers all key aspects: purpose, parameter roles, safety, and preview. Minor omission of return value specification, but adequate for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline is 3. The description adds value by explaining the confirm parameter's behavior (preview vs execute) and provides concrete examples, exceeding the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Delete a Salesforce record by Id.' which clearly identifies the verb (delete), resource (Salesforce record), and method (by Id). It distinguishes from siblings like sf_create, sf_update, and sf_read, and also from delete tools for other systems.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit safety instructions explain when to pass confirm=true vs false, including the preview mode. This provides clear guidance on usage context. It does not directly compare with alternative tools, but the safety emphasis compensates.
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?
No annotations provided, but description explicitly states it returns profile, roles, and group memberships, indicating a read operation with no side effects disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences clearly separate purpose and input specification, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with one parameter and no output schema, description sufficiently covers purpose, inputs, and return value; missing error handling details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with description for identifier; description adds nuance by specifying 'name (first/last)' versus schema's 'full name', enriching meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Describes a specific verb 'Look up' and resource 'ServiceNow user', clearly distinguishing from sibling tools like sn_create_user or sn_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly states the accepted input types (username, email, name, sys_id) but lacks explicit guidance on when to use this tool versus alternatives like sn_read.
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 no annotations, the description fully discloses behavior: for SN->external it touches a record and polls, for external->SN it POSTs a payload and verifies. It mentions 'harmless field' to indicate non-destructive side effect. Could add more on polling timeout or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with paragraphs for each direction and a list for return. It is relatively long but each section serves a purpose. Minor wordiness could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explicitly states the return (pass/fail verdict, responses, correlation state). It covers both directions, all parameters, and the high-level flow. Complex tool needs this completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters have schema descriptions, and the description adds context: 'prefix' linked to design_integration plan, direction modes with clear usage, and conditional parameters explained per direction. This adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's action (send test payload and verify) and the resource (bidirectional integration). It distinguishes between two directions and differentiates from sibling tools focused on other integration 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each direction and the required parameters based on direction. It does not explicitly state when not to use the tool or list alternatives, but the context is clear and adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states the tool sorts and returns the sorted order, implying a read-only operation. It does not mention destructive behavior, permissions, or error handling, but for a sorting tool, the key behavior is adequately 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no redundancy. The first sentence states the core function, the second provides a usage example, and the third specifies inputs and outputs. Information is front-loaded and every sentence is meaningful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description mentions the return value (sorted order) and inputs. It is mostly complete, though it could mention handling of cycles or invalid edges. However, given the tool's simplicity, the description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description adds value by explaining the edges format as [parentId, childId] pairs and reinforcing the purpose of nodes as identifiers. This goes beyond the schema's terse descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sorts a list of entity types or record IDs in dependency order (parents before children). It specifies the output as sorted order and gives a concrete use case (relationship-aware migration). This distinguishes it from siblings like analyze_dependencies which likely analyze rather than sort.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for when to use the tool (relationship-aware migration) with an example. However, it does not explicitly state when not to use it or mention any alternatives among siblings, but the unique purpose makes it implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses that the tool performs analysis, can fetch live data from ServiceNow, and returns various metrics. Since it is a read-only analysis, side effects are not expected, and no contradictions are present. It could mention that connectivity is needed for mode B.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear first sentence for purpose, followed by bullet points for input modes and returns. 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers inputs, outputs, and usage order adequately. It lacks details on error handling, prerequisites for mode B, or behavior if both modes are supplied, but it is sufficient for an AI to understand how to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining the two modes (code vs. artifact_type+name/sys_id) and how each parameter is used, which goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: deep-analyze a ServiceNow artifact to understand testing needs. It distinguishes itself from sibling tools like analyze_dependencies and analyze_flow by focusing specifically on testing analysis. The input modes and return fields are explicitly listed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Always call this FIRST before create_test_plan', providing a strong usage guideline. It also describes two input modes. However, it does not explicitly mention when not to use the tool or suggest alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses the destructive behavior: deletion order, specific tables affected, and the requirement for explicit confirmation via the confirmed parameter. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a clear purpose statement followed by a numbered list of deleted items, use cases, and an important workflow note. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the process, prerequisites, and a note on discovery, but lacks information on return values (e.g., success message, count of deleted items). Given no output schema, this gap reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all five parameters. The description adds workflow context (e.g., importance of confirmed) but does not provide additional semantic details beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes all migration artifacts created during setup, listing specific types and order. This verb+resource definition is unambiguous and distinguishes from siblings like cleanup_migration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (e.g., after failed setup, restart with different mappings) and provides a workflow: discover first, confirm deletion. This gives clear usage context and 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?
With no annotations provided, the description fully covers behavioral traits: credentials are held in memory only, never logged or stored, and cleared at session end. It could mention error handling for invalid credentials, but the security and lifecycle disclosure is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections, front-loads the main purpose, and every sentence adds value. It is appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers when to call, security, and follow-up steps (get_config, connect). For a credential-setting tool with no output schema, this is complete and actionable for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds a useful note about providing only needed platforms, but does not significantly augment the parameter details already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Set credentials for this session when running in web Claude Code or any context where a .env file is not present.' It uses a specific verb ('Set') and resource ('credentials'), and distinguishes from sibling tools like connect and get_config.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'WHEN TO CALL THIS' section explicitly lists two scenarios (Web Claude Code and CLI override) and provides a recommended call sequence: configure_credentials → get_config → connect. This gives clear guidance on when to use the tool versus 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?
No annotations are provided, so the description carries the full burden. It transparently lists all 9 artifacts created, implying significant system modifications. It does not contradict any annotations, and the detailed list gives the agent clear expectations about the tool's 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a well-structured bullet list that front-loads the purpose and lists all artifacts concisely. Every sentence adds value; no filler. The one-sentence usage note at the end is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (creating 9 artifacts) and the absence of an output schema, the description thoroughly explains what is created. It might be improved by mentioning the return value or success confirmation, but overall it is complete enough for an agent to understand the tool's effect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds critical context beyond the schema: it explains that 'plan' must come from design_integration, 'target_url' is the base URL of the target platform API, and 'target_api_key' is an API key for the target platform. This significantly enriches the parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create all ServiceNow-side artifacts for a bidirectional integration' and lists every artifact type (correlation table, retry/error table, etc.). This clearly distinguishes it from sibling tools like 'create_sf_integration_artifacts' or 'create_jira_integration_artifacts' by focusing specifically on the ServiceNow side.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'Requires the integration plan from design_integration,' which provides clear context for when this tool should be used (after design integration). However, it does not explicitly mention when not to use it or suggest alternative 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?
Given no annotations, the description fully covers behavior: it returns root causes, diagnosis steps, fix code, prevention tips, and suggested MCP tools. It does not mention any modifications, auth needs, or rate limits, but as a diagnostic tool, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and structured with a bulleted list of categories and examples. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary aspects: purpose, input examples, categories, and detailed return values. Despite no output schema, the agent knows exactly what to expect. It is complete for a diagnostic tool with two parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds value by providing examples for the 'symptom' parameter and listing all categories. However, it does not elaborate on the 'category' parameter beyond the enum values in the schema. Schema coverage is 50%, but the description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool diagnoses ServiceNow issues from symptom descriptions and returns guided fixes. The verb 'diagnose' and resource 'ServiceNow issue' are specific, and the listed categories and examples differentiate it from sibling diagnostic tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when a symptom description is available and lists covered categories and examples. It does not explicitly state when not to use or compare to alternatives, but the context is clear enough for an AI 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?
No annotations provided, so description carries full burden. It explains the non-destructive nature ('without deleting them') and what components are affected, but could mention potential side effects or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey purpose, usage, and next steps. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple tool with one parameter and no output schema, description provides sufficient context: action, when-to-use, and sibling reference. 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'prefix' with schema description 'Integration prefix'. Description does not add extra meaning beyond schema. 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it pauses a bidirectional integration by deactivating specific components (Business Rule and Scripted REST API), distinguishing it from the sibling enable_integration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions use cases: maintenance windows, debugging, bulk imports, and provides instruction to call enable_integration to resume.
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 no annotations provided, the description carries the full burden. It discloses the destructive nature (deletes records), the identification via correlation prefix, and the two-phase commit. It could mention permissions or irreversibility, but the two-phase pattern adds valuable context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: first defines the tool's function, second gives an example prefix, third explains the two-phase process. Every sentence adds value with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with three parameters and no output schema, the description is fairly complete. It explains the two-phase pattern and criteria for deletion. It could mention expected output (e.g., count for confirm=false), but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, but the description compensates by explaining the correlation_prefix parameter with examples ('jira:', 'salesforce:'), the confirm parameter (false for count, true for delete), and implies sn_table refers to target records. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes target records created by a migration, identified by a correlation_id prefix like 'jira:' or 'salesforce:'. This specific functionality distinguishes it from sibling tools such as cleanup_migration or check_migration_state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the two-phase usage pattern (first confirm=false to see count, then confirm=true to delete). However, it does not explicitly state when not to use this tool or provide alternatives, which would enhance 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?
No annotations provided, yet the description fully discloses behavior: creates Fix Script records, attempts execution via SN API, fallback to MANUAL_REQUIRED, returns PASS/FAIL/MANUAL_REQUIRED/ERROR, and detailed report with score%, verdict, remediation. After-execution actions are clearly outlined.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, bullet points, and bolded phases. Every sentence adds value. No redundancy or fluff. Efficiently communicates execution method, results format, and post-execution actions in a compact format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description covers execution, error modes, and post-execution steps completely. Given complexity (4 params, nested objects), it provides all necessary context for an agent to use correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 4 parameters. The description adds minimal extra beyond schema: it clarifies that 'plan' is the full plan object from create_test_plan and 'approved' is boolean for running all. Baseline 3 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute the approved test cases on ServiceNow and return a detailed results report.' The verb 'execute' and resource 'approved test cases' are specific. Among many sibling tools, this uniquely handles test execution after approval, differentiating from planning or migration tests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Only call this after the user has reviewed and approved the test plan.' Provides clear post-execution guidance for different outcomes (CRITICAL FAIL, MANUAL_REQUIRED, ALL PASS). Could mention when not to use or alternatives like retry, but overall strong 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?
Without annotations, the description carries the burden. It discloses that roles for 'user' go on sys_user_has_role and for 'group' on sys_group_has_role with inheritance. Missing details on permissions or reversibility but sufficient for core behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with clear parameter explanations and examples. Every sentence adds value without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters (3 required), no output schema. The description fully explains all parameters, actions, and target types with examples, covering the necessary context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only target and roles have descriptions). The description compensates by explaining target_type and action in detail, including what each enumeration does, and provides examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Assign or revoke roles on a ServiceNow user or group.' It distinguishes from sibling tools like sn_list_roles by focusing on assign/revoke 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use user vs group target and the three actions (assign, revoke, list). It provides examples but doesn't explicitly state when not to use this tool or compare with 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?
With no annotations provided, the description carries full burden. It discloses it queries live instances, returns a ranked list plus a fallback, and requires user confirmation. Could mention if the call is read-only or has performance implications, but overall sufficient for an interactive suggestion tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and well-structured: immediate directive, what it does, return format, and usage instructions. No superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains return format (ranked list + fallback) and how to use the result (present to user, get confirmation). Covers all necessary context for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a clear description. The description adds context ('source platform', 'source object name') and examples but does not significantly augment the schema beyond reinforcing the 'source' aspect. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to query live ServiceNow tables and rank them by similarity to a source object name, intended as a precursor to discover_schema. It distinguishes from siblings like discover_schema and find_table by explicitly using 'BEFORE discover_schema' and 'suggestions'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use ('when the user has not told you which ServiceNow table to migrate into') and a strong directive to NEVER guess, always call this first. It also instructs to present suggestions and ask for confirmation, covering both usage and 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?
Discloses that it creates multiple artifacts and skips non-automated steps. However, with no annotations provided, it does not cover side effects, idempotency, or error handling, which would 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each adding essential information: purpose, components, exception, and prerequisite. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately covers the tool's operation and prerequisites, but omits details about return values, error handling, or success criteria. Given the absence of an output schema, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all four parameters. The tool description adds context by explaining that the flow operates on the specified sn_table and that field_mappings are overrides, which adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds ServiceNow Flow Designer artifacts for a Jira Automation rule, listing specific components (flow record, trigger, condition blocks, action steps). It distinguishes from siblings like analyze_jira_automation by establishing a clear prerequisite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the prerequisite: 'Only call this after analyze_jira_automation and user confirmation.' Also notes that steps that cannot be automated are skipped, guiding the user to the manual build guide for those steps.
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 no annotations provided, the description carries full burden for behavioral disclosure. It clearly states the tool deletes records from both tables and requires user confirmation. It instructs the user to display the number of records to be deleted. While it could mention whether the deletion is reversible or what happens to associated data, it sufficiently covers the destructive nature and safety requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, about 8 lines, with a clear main sentence followed by bullet points for usage guidelines. It is front-loaded with the core action and efficiently adds important behavior instructions without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no output schema or annotations), the description provides substantial coverage of purpose, usage, and behavior. It does not explain the return value, but that is acceptable. It could mention a bit more about how the tool identifies 'records created during a migration,' but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so most parameters are already described. The tool description adds value by contextualizing the parameters: it explains that 'staging_table' and 'target_table' are used together, that 'project_keys' and 'project_field' scope the deletion, and that 'confirmed' must be true after explicit user confirmation. This adds meaningful semantic context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes records created during a migration from both staging and target tables. The verb 'Remove' and the specific resource distinction (staging and target tables) make the purpose unambiguous. It also distinguishes from siblings like 'cleanup_artifacts' by focusing on migration-created records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides three bullet points of when to use this tool (test migration cleanup, recovery from a failed migration, client-requested rollback). It also gives crucial usage guidance: always ask for explicit permission, show the user exactly how many records will be deleted, and only proceed after confirmed. This is exemplary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states that deletions are permanent and that deleting an issue removes all comments, attachments, and sub-tasks. It also requires a confirm=true flag for safety. This goes beyond the input schema by disclosing irreversible consequences and cascading effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and front-loaded with the core purpose. It groups information logically (safety, options, examples) and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key behavioral aspects and parameter usage. However, it does not mention what the tool returns upon successful deletion, which is a minor gap given 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema by explaining the resource_type options and providing usage examples. While 75% of parameters already have schema descriptions, the description clarifies when comment_id is required and confirms the purpose of confirm=true.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a Jira resource' and lists two specific resource types (issue and comment) with their effects. It distinguishes itself from sibling tools like jira_create, jira_read, and jira_update by being the only delete tool among Jira operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use each resource type and includes a safety warning. However, it does not explicitly say when not to use this tool or mention alternatives like jira_update for non-destructive changes, which would improve guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the tool returns grouped issue IDs and titles, and implies a read-only, non-destructive behavior. No annotations provided, so description carries full burden; it adequately conveys the tool's actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two main sentences plus a compact list of categories. Every sentence adds value, no redundancy, and purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description adequately covers purpose, parameter, return type, and points to a related tool. For a simple list tool with one parameter, this is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining the single optional parameter 'category', listing all possible values, and clarifying it's for filtering. This adds meaningful context beyond the schema's enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all known ServiceNow issues in the guide, with optional category filtering. It uses specific verb 'list' and resource 'common issues', and distinguishes from sibling tool get_issue_guide for 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions optional category filtering and directs users to get_issue_guide for full fix, providing context for when to use this tool. However, it does not explicitly state when not to use it or compare to other list 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?
With no annotations, the description carries full burden. It explains return values (record count, up to 5 sample records) and provides filter format details for Jira and Salesforce. It does not explicitly state it is read-only, but the preview verb implies no mutation. Minor missing details on errors or authentication but overall solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three focused paragraphs: purpose and returns, usage guidelines, and filter format. No filler, front-loaded with key info, and each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately describes return values. It covers all 4 parameters with context. It ties into sibling migration tools. A small gap is not discussing error conditions or performance impacts, but it is sufficient for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete examples for platform, filter (JQL/SOQL), and clarifying object_name as 'Jira project key or Salesforce object name'. It explains fields default to key fields. This enriches the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Preview how many records will be migrated' and distinguishes from siblings like run_full_migration and run_test_migration by explicitly advising to call this before those tools. It specifies the resource (records) and action (preview).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong usage guidance: 'ALWAYS call this before run_test_migration or run_full_migration when the user wants to filter or scope the migration'. It provides concrete examples and explicitly names alternative tools for the same context.
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?
Since no annotations are provided, the description fully carries the burden of behavioral disclosure. It details the algorithm (count check, record matching, field-level diff with transform awareness), explains how transform rules prevent false mismatches, and describes return values (verdict, per-record diffs, accuracy %). This is 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, numbered steps, and bullet points. Every sentence adds value. No unnecessary text. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, 5 required, no output schema), the description covers all essential aspects: what it does, return values, algorithm steps, and parameter roles. Missing details like error handling are acceptable for a tool of this nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining how parameters like transform_rules and date_fields are used in the algorithm (e.g., transform-awareness prevents false mismatches). This goes beyond the schema descriptions, which are already clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool performs a deep comparison between source and target records to verify migration success, listing four specific steps (count check, record matching, field-level diff, verdict). It distinguishes itself from simpler fill-rate checks, making its purpose highly specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use after a test migration or a full migration to confirm data integrity.' It provides clear context for when to use the tool but does not explicitly mention when not to use it or list alternative tools. However, the sibling tool set includes verify_migration_counts, which implies a simpler alternative.
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?
With no annotations, the description fully discloses behavior: it inspects and analyzes, returns risk scoring and recommendations. No mention of modification or destruction, consistent with a read-only analysis tool. It details what is checked and the 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with bullet points for inspections and a summary sentence. It is front-loaded with the main purpose and each sentence contributes value. No redundant or unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and no output schema, the description covers the tool's purpose, inputs, inspections, and outputs (risk scores, test recommendations). It also provides a usage ordering hint. It could be more complete by specifying the output structure, but the description suffices for an agent to decide to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 71% (5 of 7 parameters have descriptions). The description adds context by linking inspections to parameters (e.g., staging table accessibility to staging_table). It also clarifies the purpose of sample_records for null-rate analysis. However, field_mappings and transform_rules have no schema descriptions and the description doesn't elaborate on them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool analyzes a migration setup to identify risks and plan test coverage, listing specific inspections. It distinguishes from sibling tools like analyze_dependencies and create_migration_test_plan, providing a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Always call this FIRST before create_migration_test_plan', providing clear sequential guidance. Implies usage context and alternatives (the sibling create_migration_test_plan serves as the next step).
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?
With no annotations, the description fully informs about behavior: it performs a create/update, requires both value and override_X flag, and lists supported override properties with details. It also warns about silent failures if done manually. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: first a concise action statement, then purpose, important note, supported overrides list, and examples. Every sentence adds value, and the key info is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, nested overrides object) and no output schema, the description is complete. It explains the override mechanism, lists all supported fields, and provides examples for common use cases. It covers prerequisites and best practices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, but the description adds significant value by explaining each override property with usage examples and clarifications (e.g., 'use create_choice to add child-table choices, then set this'). It also illustrates usage via code examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create or update a ServiceNow Dictionary Override on a child table.' It explains the concept of dictionary overrides and how they differ from modifying parent entries. This distinguishes it from sibling tools like delete_dictionary_override and get_dictionary_overrides.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool (for table extensions in ServiceNow) and notes that it is best practice. It implicitly guides against manual setup which often fails. However, it does not explicitly list when not to use it or specify alternatives beyond the sibling list.
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?
Without annotations, the description fully discloses behavior: returns configuration status, checks two credential sources in order, and explains the meaning of configured=false with recommended next steps. No side effects or hidden behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with bullet points. Every sentence adds value, and critical usage guidance is front-loaded. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains what the tool returns (configured status for each platform) and provides enough context to interpret and act on results. It stands alone for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline is 4. The description does not need to add parameter meaning beyond schema, which is empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Returns which platforms are configured and ready to use.' It distinguishes from siblings like configure_credentials by indicating it checks configuration state and should be called first.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call at the start of every session before asking the user, and provides detailed conditional actions based on configured flags and credential sources. It also advises when to call configure_credentials and when to inform the user about missing .env variables.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

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

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

Card Badge

Copy to your README.md:

[![ServiceNow-Dev-MCP MCP server](https://glama.ai/mcp/servers/pinnintisagarSB/ServiceNow-Dev-MCP/badges/card.svg)](https://glama.ai/mcp/servers/pinnintisagarSB/ServiceNow-Dev-MCP)

Score Badge

Copy to your README.md:

[![ServiceNow-Dev-MCP MCP server](https://glama.ai/mcp/servers/pinnintisagarSB/ServiceNow-Dev-MCP/badges/score.svg)](https://glama.ai/mcp/servers/pinnintisagarSB/ServiceNow-Dev-MCP)

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/pinnintisagarSB/ServiceNow-Dev-MCP'

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