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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.