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

Discloses use of Aggregate API for efficiency with fallback to limited fetches, adding context beyond annotations (readOnlyHint, idempotentHint). Does not contradict annotations.

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

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

Front-loaded with purpose, then details on counts, then usage note. Moderately concise; the Args/Returns section is helpful but could be integrated more tightly.

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 input, behavior, and output (with output schema present). Lacks details on error handling or fallback cases, but is sufficient for an agent to use the tool effectively.

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

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

With 0% schema description coverage, the description compensates by explaining the parameter ('table') is a CMDB table and provides an example ('cmdb_ci_server'), adding meaning beyond the schema's bare type.

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 produces a summary of all configurables for a CMDB table, listing the specific types counted (business rules, client scripts, etc.), and distinguishes from siblings that retrieve individual configurable types.

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 advises use 'for a quick audit ... before making changes', which is a specific use case. While it doesn't list alternatives, the context of sibling tools for individual getters implies when to use them instead.

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

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

Annotations declare readOnlyHint, destructiveHint, idempotentHint. The description adds valuable behavioral details: returns instance URL, username, directly-assigned roles (not inherited), and that no parameters are required. 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?

Concise, front-loaded with purpose, bulleted verification points, and clear return fields. Every sentence is useful and well-structured.

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

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

Given the tool's simplicity (0 parameters, output schema exists but described), the description provides all necessary context, including return structure and verification steps.

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?

No parameters in schema, and description confirms 'No parameters required.' This adds clarity beyond the schema, but the value is modest since the schema already implies no input.

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 checks connectivity and authentication to a ServiceNow instance, with specific verification criteria (credentials, reachability, access). It distinguishes itself from sibling tools that focus on CMDB, CIs, 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?

Explicitly advises calling at the start of any workflow, providing clear usage context. No alternative tools perform the same function, so no exclusion needed.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. Description adds that it uses Aggregate API calls (no record fetches), which is a key behavioral trait beyond annotations.

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

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

Well-structured with a summary line, bullet list of metrics, usage guidance, and args/returns sections. Slightly verbose but each 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 the output schema exists (not shown), the description adequately covers the return format by listing keys. It explains the tool's purpose, parameters, and behavioral traits completely.

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 has no descriptions (0% coverage). Description explains both parameters: ci_class as the CMDB table to summarize, stale_days as the threshold for staleness, with defaults and examples, fully compensating for the schema gap.

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 'Produce an overall CMDB health summary with key metrics' and lists specific indicators. It distinguishes itself from sibling tools like find_orphan_cis by noting that it provides a summary, not detailed 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?

Explicitly tells when to use the tool: for efficient overview using aggregate calls, and when to use alternative tools for detailed results. Provides parameter guidance with defaults.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds important behavioral context: token is single-use and expires after 5 minutes, plus return fields (success, sys_id, table, created_record). Does not contradict annotations.

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

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

Two brief paragraphs with structured Args and Returns sections. Front-loaded with main purpose. No unnecessary 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?

Given the tool has one required parameter and an output schema (not shown but present), description covers prerequisites, token behavior, and return format. Could mention what type of CI is created, but overall complete for a focused action 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 has 0% description coverage for the single token parameter. Description compensates by explaining 'The confirmation token from preview_ci_create', adding meaning beyond the type 'string' in 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?

Description clearly states 'Execute a previously previewed CI creation' with specific verb 'execute' and resource 'CI creation previewed earlier'. Distinguishes from sibling tools like preview_ci_create (preview vs execute) and confirm_ci_update (CI update).

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 prerequisite: 'You MUST call preview_ci_create first and use the token from its response.' Also mentions token expiry (5 minutes) and single-use constraint. Provides clear guidance on when to use this tool.

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

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

Beyond annotations (destructiveHint=true, idempotentHint=true), the description adds critical behavioral details: the token lifecycle (single-use, 5-minute expiry) and that it executes a previewed update, which aligns with the idempotent hint.

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 one-sentence summary of the action, then prerequisites, parameter details, and return value. Every sentence adds value with no wasted words.

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

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

Given the simple one-parameter tool and existing output schema, the description fully covers the execution flow, token constraints, and expected results, making it complete for an agent to correctly invoke the tool.

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

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

Despite 0% schema description coverage, the description thoroughly explains the token parameter as 'The confirmation token from preview_ci_update', adding meaning beyond the schema's bare title.

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 executes a previously previewed CI update, using a specific verb and resource. It distinguishes from sibling tools like preview_ci_update and confirm_ci_create by explicitly requiring a token from preview_ci_update.

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 prerequisites: Must call preview_ci_update first and use the returned token. It also notes the token is single-use and expires after 5 minutes, giving clear usage context and when-not-to-use alternatives.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds useful context: uses Stats API, supports grouping, returns JSON. 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 examples and parameter list. Slightly lengthy but every sentence adds value. Could be slightly more 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?

Completely covers the tool's purpose, parameters, return value, and usage. With output schema present, description explains aggregate result behavior adequately.

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

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

With 0% schema description coverage, description compensates by explaining each parameter with defaults and examples. Clear and helpful.

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 it counts configuration items using the Aggregate API, distinguishing from sibling tools like search_cis and query_cis_raw. Uses specific verb 'count' and resource 'configuration items'.

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

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

Provides examples and implies use for efficient counting instead of fetching records. Lacks explicit when-not-to-use or alternative comparisons but 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?

Annotations declare readOnlyHint, destructiveHint, idempotentHint. Description adds: queries sys_dictionary and cmdb_rel_type_suggest, includes inherited fields, results cached for 1 hour.

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: purpose sentence, internal details, usage guidance, prerequisites, args, returns. No fluff, 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?

Complete coverage: purpose, how it works, when to use, prerequisites, parameter details, return structure. No gaps given tool complexity and existing 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?

Schema coverage is 0%, but description fully explains class_name with examples and summary parameter with behavior difference between True/False.

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 it gets field definitions, descriptions, and suggested relationships for a CMDB class. Differentiates from siblings like list_ci_classes (lists class names) and suggest_table (finds right class).

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

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

Explicitly says when to use: to understand schema before building queries or check available fields/relationships. Provides prerequisites (use list_ci_classes or suggest_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?

Annotations already indicate readOnlyHint, destructiveHint, idempotentHint. Description adds that table names are validated and dangerous query patterns are blocked, which provides extra behavioral context beyond annotations.

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

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

Description is concise with a clear purpose, safety note, and parameter list. It is front-loaded with the main action. A few words could be trimmed, but overall 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 has 3 parameters, a single required param, no nested objects, and an output schema (not needing return value explanation), the description covers purpose, usage context, safety, and parameter details adequately for an AI 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 coverage is 0% (no descriptions in JSON schema), but the description explains each parameter: table (ServiceNow table to probe), query (optional encoded query filter), limit (max records, default 3). This adds meaning beyond the schema's titles and types.

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 it is a temporary diagnostic tool to probe any ServiceNow table to check access. The description includes the verb 'probe', the resource 'table', and distinguishes it from sibling tools focused on CI and discovery operations.

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

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

Explicitly states it is for troubleshooting only and mentions safety measures (validated table names, blocked dangerous patterns). Does not specify alternatives or when not to use, but the context implies it is for access checks.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds context: it fetches both CIs and identification rules, compares fields, and returns a JSON with key fields, rules, and comparison. 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 concise, front-loaded with purpose, then covers behavior, prerequisites, example, and parameters. Each 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 tool's complexity, the description covers prerequisites, parameters, process, and return value summary. Output schema exists, so detailed return fields are not needed. Complete for effective 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 description coverage is 0%, but the description provides a detailed 'Args:' section documenting each parameter (sys_id_a, sys_id_b, table) and their purpose, adding meaning beyond the input schema's titles and types.

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 purpose: 'Explain why two CIs might be duplicates by comparing their identification fields.' It then details the process, distinguishing it from sibling tools like find_duplicate_cis.

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: 'Prerequisites: Use find_duplicate_cis to identify the duplicate pair first.' This tells when to use the tool and when not to. Also provides an example and argument 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?

Annotations already show readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds rich behavioral context: bidirectional BFS, 10 relationships per node per direction limit, 60-second timeout, and detailed return fields. No contradiction.

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

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

Well-structured with clear sections (purpose, algorithm, prerequisites, performance, examples, args, returns). Front-loaded key information, every sentence adds value, no fluff.

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

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

Complete coverage: algorithm, limits, prerequisites, return format, examples, and error conditions (timeout). Given tool complexity, description leaves no 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 description coverage is 0%, so description fully explains each parameter: source_sys_id and target_sys_id as CI identifiers, max_depth with default 5, range 1-10, and behavioral impact on API calls. Adds significant meaning 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 finds the shortest relationship path between two CIs using bidirectional BFS. It distinguishes from sibling tools like find_related_cis and get_dependency_tree by focusing on pathfinding between two known endpoints.

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

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

Provides clear when-to-use: 'useful when you know both endpoints and want to understand how they are related without traversing the full tree.' Also includes prerequisites (use search_cis first) and performance limits. Lacks explicit when-not-to-use but 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?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by explaining the grouping logic ('grouping CIs on a field and returning groups with more than one record') and pagination behavior (limit, offset, has_more, next_offset). This goes beyond the annotations.

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

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

The description is well-structured: a one-line summary, a paragraph explaining the logic, three examples, a bullet-style args section, and a returns section. Every sentence adds value, and it is front-loaded with the 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?

Given 5 parameters (none required) and an output schema, the description explains the return structure ('duplicate_groups' list) and pagination fields. No critical gaps remain for an agent to understand input/output.

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 0% description coverage, so the description carries full burden. It explains each parameter: ci_class (defaults to cmdb_ci), match_field (lists common choices like 'name', 'serial_number'), name_filter (STARTSWITH filter), limit (range 1-1000, default 25), offset. Examples demonstrate usage.

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

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

The description starts with a clear verb+resource: 'Find CIs that share the same value for a given field within a class.' It specifies the grouping logic and provides examples that differentiate it from siblings like 'explain_duplicate' (which explains a specific duplicate rather than finding all).

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

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

The description states it is 'useful for finding CIs that may have been created by multiple discovery sources or manual entry,' giving context for use. However, it does not explicitly say when not to use it or compare with alternatives like 'explain_duplicate' or 'search_cis,' leaving room for misinterpretation.

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

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

Annotations already indicate read-only, non-destructive, idempotent. Description adds that multiple API calls are made per batch, results may be partial, and scan_offset allows continuation. No contradiction with annotations.

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

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

Well-structured with sections, examples, and front-loaded purpose. Slightly verbose with redundant explanations (e.g., definition of orphans), but overall clear 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?

Covers all aspects: purpose, parameters, return values (described in text), performance, examples, and continuation logic. Output schema presence and description ensure 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 0%, but the 'Args' section describes each parameter, including defaults, enum meanings (e.g., operational_status '1' for Operational), and usage tips. This fully compensates for missing 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 finds CIs without relationships, defines orphan CIs, and distinguishes from sibling tools like cmdb_health_summary. Examples and parameter details reinforce the purpose.

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

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

Explicitly explains when to use this tool (find orphans) and when to use alternatives (cmdb_health_summary for quick count). Provides performance guidance and recommends narrowing scope to reduce cost.

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

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

The description adds behavioral context beyond annotations, explaining that rel_type can be a sys_id or name (resolved to sys_id), direction options, and return structure. It complements the readOnlyHint and idempotentHint annotations 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?

The description is well-structured with a concise overview, parameter explanations, and return format. Every sentence adds value without redundancy.

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

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

Given the complexity of 5 parameters and the existence of an output schema, the description covers inputs, behavior, and output fields comprehensively. It is fully self-contained.

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

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

With 0% schema coverage, the description fully explains each parameter: ci_sys_id, rel_type (with type resolution), direction (enum, default), limit (range 1-1000, default 25), and offset (pagination). This provides complete semantic 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 clearly states the tool finds CIs related to a given CI by relationship type. It is specific and distinguishes this from generic search tools, though it doesn't explicitly differentiate from sibling tools like get_ci_relationships.

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 what the tool does and how to use parameters, but it does not provide guidance on when to use this tool versus alternatives like get_ci_relationships or find_ci_path.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the bar is lower. The description adds context about default filtering to operational CIs and the ordering of results (most stale first). It does not contradict annotations and discloses the return format beyond the schema.

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

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

The description is well-structured with a clear purpose, contextual explanation, examples, parameter list, and return format. It is front-loaded and each section adds value, though it could be slightly more concise without the examples.

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 5 parameters and the presence of an output schema, the description comprehensively covers all aspects: parameter details with defaults and ranges, return fields and ordering, and a motivating use case (broken discovery). It is 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?

Schema description coverage is 0%, so the description carries the full burden. It provides detailed explanations for all 5 parameters, including defaults, allowed values, constraints (e.g., days between 1-3650), and behavioral contexts like the operational_status default. This fully compensates for the missing 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 finds CIs not updated within a specified number of days, defines 'stale' based on sys_updated_on, and provides examples. It does not explicitly differentiate from sibling tools like search_cis or find_orphan_cis, but the specific purpose is distinct enough for an agent to understand.

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 detecting potentially broken discovery or decommissioned assets via stale CIs, but it lacks explicit guidance on when to use this tool versus alternatives. No exclusion criteria or recommendations for when not to use it are 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?

The description supplements the annotations (readOnly, non-destructive, idempotent) by noting that script conditions are redacted for credentials and that include_scripts controls whether redacted bodies are returned. It also describes the return structure, adding transparency beyond what annotations provide.

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

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

The description is well-organized with clear Args and Returns sections, front-loading the purpose. While it is somewhat lengthy, every sentence adds value—explaining redaction, defaults, and return fields. It could be slightly tighter, but it's efficient 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?

Given that an output schema exists, the description's detailed return description is complementary. It covers all parameters, behavioral nuances (redaction, defaults), and pagination. No gaps are apparent for a tool of this moderate 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?

With 0% schema description coverage, the description fully explains all five parameters: table (CMDB table example), active_only (default True), include_scripts (default False with token efficiency hint), limit (range 1-1000, default 25), offset (pagination). This provides essential meaning missing from 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 retrieves ACL rules for a CMDB table, specifies the underlying table (sys_security_acl), and lists what operations are covered. While it's unambiguous and uses a specific verb-resource combination, it does not explicitly differentiate from sibling tools; however, no sibling appears to share this focus, so it's clear enough.

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 what the tool does but lacks explicit guidance on when to use it versus alternatives or when not to use it. The context suggests this is the only tool for ACL inspection among siblings, so reliance on implicit understanding is acceptable, but direct usage guidance is absent.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds value by noting that script bodies are redacted for credentials and explaining default parameter behaviors, providing useful context beyond annotations.

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

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

The description is well-structured with clear sections (Args, Returns) and front-loaded purpose. It is efficient but not overly concise; a few sentences could be trimmed, but overall it's well-organized and readable.

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 5 parameters and an output schema. The description explains the return structure (table, count, total_count, etc.) and parameter behavior, covering essential aspects. Slight gaps (e.g., explaining active_only defaults) exist, but overall it's 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?

Given 0% schema description coverage, the description fully compensates by describing each parameter in the Args section: table, active_only, include_scripts, limit, offset. It explains defaults and purpose, adding significant meaning beyond the bare 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 retrieves business rules from a CMDB table, specifying the operations (insert, update, delete, query). This verb+resource combination distinguishes it from sibling tools focusing on CI, discovery, or other aspects.

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 when to set include_scripts=True for reviewing logic and notes token efficiency. It implies usage context for business rule inspection but does not explicitly contrast with alternatives or state when not to use this tool.

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

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

The description is consistent with annotations (readOnlyHint, destructiveHint false, idempotentHint). It adds context about default field behavior, display_value options, and error handling (NotFoundError for non-existent sys_id). No contradictions with annotations.

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

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

Well-structured with clear sections (purpose, prerequisites, examples, arguments, returns). Front-loaded with core purpose. However, the default fields list is quite lengthy; while informative, it makes the description somewhat verbose. Still excellent overall.

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 (1 required) with detailed descriptions, and an output schema (present but not shown), the description covers all parameter behaviors, return value structure, and error case. It fully equips an agent to use the tool correctly.

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

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

Schema coverage is 0%, so description carries full burden. It explains each parameter: sys_id (32-character hex), table (with default and efficiency tip), fields (default broad set listed), display_value (three modes with examples). Adds significant meaning beyond the raw 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 'Get the full details of a single configuration item by its sys_id', specifying the verb, resource, and key identifier. It distinguishes itself from sibling tools like search_cis (which finds CIs) and query_cis_raw (which may have different querying capabilities).

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

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

Explicitly states when to use: 'when you need complete information about a specific CI, such as after finding it via search_cis'. Provides prerequisites (use search_cis or query_cis_raw to find sys_id), and explains that it only accepts sys_id (not CI names), with an example of how to look up by name.

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

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

Annotations already indicate readOnly, non-destructive, idempotent. The description adds meaningful context: upstream/downstream CMDB model, pagination details, and return structure. 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 sections, examples, and parameter list. Every sentence adds value, though slightly lengthy. Information is front-loaded.

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

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

Complete for a read-only query tool: explains prerequisites, parameters, direction semantics, pagination, and return format. Output schema exists, but description adds practical context. Distinguishable from siblings.

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 0% schema coverage, the description thoroughly explains all parameters: ci_sys_id (32-char hex from search_cis), direction (enum with defaults), limit (range 1-1000), offset (pagination). Adds semantic meaning 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 the tool gets all relationships for a configuration item, specifies upstream/downstream/both, and lists included fields. It distinguishes from siblings by focusing on relationships and referencing search_cis for name lookup.

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 prerequisites (use search_cis for sys_id), explains direction terminology, provides examples, and warns against using CI names directly. This fully guides when and how to use the tool.

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

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

Annotations already indicate read-only, non-destructive, idempotent. The description adds that script bodies are redacted for security and explains pagination behavior (has_more, next_offset), providing valuable context beyond annotations.

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

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

The description is well-structured with clear sections for description, args, and returns. Every sentence adds essential info; no fluff. Front-loaded with 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?

Given the tool's moderate complexity and presence of an output schema, the description explains the return structure (table, count, total_count, has_more, next_offset, client_scripts list with fields) comprehensively, leaving no 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 description coverage is 0%, but the description fully compensates by explaining each parameter: table (example given), active_only, include_scripts (with token-efficiency rationale), limit (range), and offset. No ambiguity remains.

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 retrieves client scripts (onChange, onLoad, onSubmit, onCellEdit) for a specified CMDB table, distinguishing it from sibling tools like get_business_rules or get_script_includes.

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 parameter usage (e.g., include_scripts only when needed) and defaults, but does not explicitly contrast with alternatives for server-side scripts, which would strengthen 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 adds significant behavioral context beyond the annotations: exponential API call growth with depth, 60-second timeout behavior, class_filter traversal behavior (filtered out but still traversed), and return shape differences between formats. No contradictions with annotations.

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

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

The description is well-structured with clear sections (purpose, prerequisites, performance, examples, args, returns). Every sentence adds value, but it could be slightly more concise. The length is justified by 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?

Given the tool's complexity (6 parameters, output schema exists), the description is exceptionally complete. It covers behavior, performance constraints, return values for both formats, and edge cases (timeout, partial results). The output schema provides additional detail but the description adds usability 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?

With 0% schema description coverage, the description thoroughly explains all 6 parameters: ci_sys_id (hex string from search_cis), direction (upstream/downstream meanings), max_depth (range, default, performance impact), limit_per_level (breadth control), class_filter (filtering behavior, example), and format (json vs ascii_tree output). This fully compensates for the missing 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 walks the dependency tree from a CI with configurable depth and direction. It uses specific verbs ('walk', 'build a tree') and distinguishes from sibling tools like get_ci_relationships by emphasizing recursive traversal and configurable depth/direction.

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 when to use the tool (understanding full dependency chain) and provides prerequisites (use search_cis first). It also gives performance guidance on starting with lower depth. However, it does not explicitly state when not to use or mention alternative tools for simpler dependency queries.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds value by detailing parameter behaviors like severity defaulting to 'Error' and the effect of setting max_message_length to 0, which goes beyond the annotations.

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

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

The description is structured with a summary line, a usage paragraph, an Args list, and a Returns section. Every sentence adds value without redundancy or unnecessary length.

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 presence of an output schema and annotations, the description adequately covers the tool's behavior and return format. It mentions pagination via offset but could be more explicit about how pagination works across multiple calls.

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

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

With 0% schema description coverage, the description fully compensates by explaining each parameter: severity filtering with empty string option, days range, limit, offset, and max_message_length truncation behavior. It also documents default values and edge cases.

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 'Get recent Discovery error and warning log entries' and specifies it queries the discovery_log table. This precisely differentiates it from sibling tools like get_transform_errors and get_discovery_status.

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 advises using the tool to 'diagnose why CIs are not being discovered or updated correctly', providing clear context for when to use it. However, it does not explicitly mention when not to use it or list alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds context about querying the discovery_status table and returning records with success/fail/in progress states, which is consistent but adds limited value beyond the annotations.

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

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

The description is well-structured with Args and Returns sections, and each sentence serves a purpose. It is slightly verbose but efficient, 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 output schema exists, the description sufficiently explains return fields (count, statuses list with sys_id, state, source, etc.). All parameters are optional, and the tool's purpose is fully covered. No 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 description coverage is 0%, but the description's Args section details all four parameters, including schedule_name's STARTSWITH matching, state's valid enum values, limit range (1-1000), and offset for pagination. This provides 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?

The description clearly states 'Get recent Discovery status records showing scan results', which is a specific verb+resource. It further explains that it queries the discovery_status table for scan results, distinguishing it from sibling tools like get_discovery_errors or list_discovery_schedules.

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 parameter descriptions and context (e.g., schedule_name supports STARTSWITH match) but does not explicitly state when to use this tool versus siblings or when not to use it. Usage is implied but not explicitly 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is covered. The description adds behavioral context: it fetches from sys_hub_flow_base, parses the label_cache, and optionally fetches step details from additional tables, including role requirement for details. This adds value beyond annotations without contradiction.

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

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

Description is well-structured with a clear opening sentence, then prerequisites, examples, args, and returns. It is front-loaded with purpose. While slightly verbose, each section earns its place and provides necessary detail 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 an output schema exists (though not shown), the description's return value listing is sufficient. It covers flow metadata, steps, step count, and optional detailed steps. It mentions role requirements and efficiency. However, it omits error handling or cases like invalid sys_id, so it's not fully exhaustive.

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?

Input schema has 2 params with 0% description coverage. Description compensates by explaining sys_id must come from get_flows, and include_step_details fetches step configuration, requires fd_read role, and defaults to false for efficiency. This adds significant meaning beyond the schema's bare property definitions.

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 action ('Get detailed logic of a Flow Designer flow by sys_id'), specifies the resource (flow details), and distinguishes from sibling get_flows by explaining it's the prerequisite to find the sys_id. It also lists what is returned (metadata, steps, etc.), making the purpose unambiguous.

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

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

Description provides explicit prerequisites ('Use get_flows to find the flow sys_id first'), usage context for include_step_details (role requirement, efficiency trade-off), and examples. While it doesn't explicitly mention when not to use it, the guidance is clear and actionable. Sibling differentiation is implicit through the prerequisite mention.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds context: searches sys_hub_flow, notes trigger/action details are in sub-tables (limitation), and lists return fields. No contradiction.

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

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

Well-structured with examples, args list, and clear sections. Slightly verbose but every sentence adds value. Front-loaded with main 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 5 parameters, annotations, and output schema, the description covers input, output, limitations, and usage. Output schema exists, so return format is not needed in description. Complete for the tool 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 coverage is 0%, but description fully explains each parameter with defaults, examples, and constraints. Also details return JSON structure, 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 it retrieves Flow Designer flows by internal_name or display name, with specific criteria. It distinguishes from siblings like 'get_flow_details' by noting it provides an overview.

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 requires at least one of table or name_filter. Provides examples. Implicitly contrasts with 'get_flow_details' and ServiceNow UI, but does not explicitly list when-not-to-use.

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

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

Annotations already indicate readOnlyHint, destructiveHint, idempotentHint. The description adds context by detailing the output structure (JSON with count and identification_rules list including name, applies_to, identifier fields, priority, active status) and the effect of parameters. 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-organized with clear sections for Args and Returns, and is informative without being overly verbose. Minor redundancy (e.g., 'Optional — omit to list rules for all classes' could be shortened) but overall effective.

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

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

Given the tool has 4 parameters and an output schema, the description covers input parameter semantics and output structure adequately. It does not mention error handling or side effects, but for a read-only, idempotent operation this is acceptable. The presence of an output schema shifts the burden away from describing return values, and the description still provides useful detail.

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

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

With schema description coverage at 0%, the description fully compensates by explaining each parameter: table filters by CI class (optional), active_only (defaults to True), limit (1-1000, default 25), offset (pagination). This adds critical meaning beyond the raw 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 'Get CMDB Identification and Reconciliation Engine (IRE) identification rules' and explains their role in matching incoming data to existing CIs. It specifies the resource (identification rules) and action (get), and the context differentiates it from sibling tools like get_reconciliation_rules.

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

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

The description explains the purpose of identification rules and provides parameter details (e.g., table filter, active_only default). It implies when to use (retrieving matching rules) but does not explicitly state when not to use or compare to alternatives. However, for a straightforward read operation, the guidance is clear.

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

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

Discloses performance characteristics (many API calls, 60s timeout), traversal behavior, and the timed_out flag. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint all consistent).

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 clear sections, examples, and parameter descriptions. Slightly verbose but every part adds value; could be tightened slightly 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?

Covers all necessary aspects: purpose, prerequisites, performance, timeout, parameter details, return structure. Output schema exists and description lists returned fields, so no 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 0%, but the description fully explains all three parameters: ci_sys_id (format, source), max_depth (range, default), class_filter (optional, filtering behavior). Examples illustrate usage.

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 produces a summary of impacted services and applications for a given CI, with specific use cases like blast radius analysis and change risk assessment. It distinguishes from sibling tools by focusing on impact assessment rather than raw listing or details.

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

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

Explicitly tells when to use (change impact assessment, blast radius) and provides prerequisites (use search_cis first). Also gives performance recommendations (start with max_depth=2) and explains timeout behavior.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, indicating safe, read-only behavior. The description adds valuable context: it explains the returned fields (completion status, row counts, errors) and notes that state values 'may vary by instance configuration'. 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 with a brief overview followed by a clear list of parameters. It is efficient, though the parameter details could be slightly more integrated. However, it remains easy to read and front-loaded with 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?

With annotations covering safety and idempotency, and an output schema existing, the description adequately covers the tool's behavior. It explains the return structure and parameter constraints. Minor omission: no mention of pagination behavior beyond offset or time range limitations, but overall sufficient for the tool's complexity.

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

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

The input schema has 0% description coverage, but the description's 'Args' section fully compensates by explaining each parameter: table_name (STARTSWITH match), state (common values with caveat), days (range 1-365, default 7), limit (1-1000, default 25), and offset (pagination). This adds meaning far beyond the schema's titles and defaults.

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 'Get recent import set run records' and explains what an import set run represents, along with the information returned (completion status, row counts, errors). This verb+resource combination is specific and distinguishes it from sibling tools, which focus on other aspects like CI details or errors.

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 explicitly state when to use this tool versus alternatives, nor does it provide 'when-not-to-use' guidance. While the resource is unique among siblings, the lack of explicit usage context limits the score to average.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by explaining the conceptual behavior (how rules work) and the return format. It does not introduce contradictions or undisclosed traits, but also doesn't detail edge cases or error handling.

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

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

The description is well-structured with a concise opening, concept explanation, parameter documentation, and return format. Every sentence adds value without redundancy, making it easy for an agent to parse.

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 complexity (4 parameters, no required, no enums) and the presence of an output schema, the description fully covers all necessary information: all parameters, their meanings, constraints, and the return structure. It is complete for correct agent invocation.

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

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

With 0% schema description coverage, the description provides comprehensive parameter documentation in the Args section, including purpose, defaults, constraints (e.g., limit range 1-1000), and optionality. This fully compensates for the missing 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 with a specific verb ('Get') and resource ('CMDB IRE reconciliation rules'). It explains the domain (CMDB IRE) and distinguishes the tool from siblings like get_identification_rules by focusing on reconciliation rules and their role in conflict resolution.

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 what reconciliation rules are and their purpose, but it does not provide explicit guidance on when to use this tool versus alternatives like get_identification_rules or get_discovery_status. The usage context is implied but not directly addressed.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by noting that include_scripts defaults to false for token efficiency and that script bodies are redacted. This provides behavioral context beyond the annotations, such as an implicit performance consideration. 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: a clear purpose, background explanation, usage context, three concise examples, parameter descriptions, and return value specification. Every sentence adds value, and 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?

Given the tool's complexity (5 parameters, pagination, output schema) and numerous siblings, the description covers all necessary aspects: what the tool does, when to use it, parameter details with defaults, return structure (count, total_count, has_more, etc.), and performance implications. It is complete and self-contained.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains each parameter: name_filter is a case-insensitive LIKE match, active_only defaults to True, include_scripts is for reviewing logic with a token efficiency note, limit has a range 1-1000 with default 25, and offset is for pagination. This fully compensates for the lack of 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: 'Get script includes matching a name filter.' It explains what script includes are and distinguishes them from business rules, making the purpose unambiguous. Examples further clarify usage, and the sibling tools are different enough (e.g., get_business_rules) to avoid confusion.

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

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

The description gives explicit context: 'Use this to find utility classes referenced by business rules, flows, or other scripts.' It provides examples illustrating when to use the tool. However, it does not explicitly state when not to use it or mention alternatives, but the context is sufficiently clear 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?

Annotations indicate read-only, non-destructive, idempotent behavior. The description adds context about truncation behavior and the fields returned, but does not mention side effects or permissions beyond what annotations imply.

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

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

The description is well-structured with an intro, Args, and Returns sections. It is fairly concise but covers all necessary details 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 has 5 parameters and an output schema, the description is complete enough. It explains the return format and edge cases like truncation, though it could add more about error handling or performance.

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 0%, but the description fully explains all 5 parameters, including default values, ranges, and special behavior for max_error_length (truncation with an extra field). This 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 retrieves recent transform map errors from import set processing. It explains the context of transform maps mapping staging to target tables, distinguishing it from siblings like get_discovery_errors and get_import_set_runs.

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 debugging transformation failures by detailing the error information returned. However, it does not explicitly state when to use this tool versus alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds valuable behavioral context: results are cached for 1 hour, and offset-based pagination may shift if classes are added or removed. This goes beyond the annotations to inform the agent about potential staleness and instability.

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 with a clear top-level purpose, followed by brief usage guidance, parameter details, return format, and a note about pagination. Every sentence adds value, and it's front-loaded with the main 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's simplicity (3 parameters, all optional), the description covers all aspects: what it does, parameters, return format (mentioning the JSON structure as per output schema), caching behavior, and a caveat about pagination. No gaps remain.

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 0% description coverage, so the description must carry the burden. It fully describes each parameter: parent_class's default and suggestion to use specific prefixes like cmdb_ci_server, limit and offset defaults, and notes on pagination. This adds significant meaning beyond the schema's bare property definitions.

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 'List available CMDB classes from the Data Model Navigator' and specifies that it returns the class hierarchy under a given parent. It distinguishes from siblings by focusing on discovering CI class structure rather than querying individual CIs or counts.

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

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

Explicitly states when to use: 'discover which CI classes exist before running queries, or to explore the CMDB class hierarchy.' While it doesn't explicitly state when not to use, the context is clear and the tool's role among siblings is evident.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by specifying the return format (JSON with count and data_sources list) and pagination behavior. It does not contradict annotations.

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

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

The description is well-structured with a lead sentence, concise context paragraph, and clear Args/Returns sections. 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 tool's simplicity (4 optional params, no enums) and the presence of annotations and output schema description, the description covers all necessary aspects: purpose, parameter details, and return structure. No gaps identified.

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 0%, so the description compensates fully by explaining each parameter, including defaults, range for limit, and optionality. This adds significant meaning beyond the schema titles.

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 'List configured import data sources' and explains their role in the CMDB. It is specific and distinct from all sibling tools, which focus on other aspects like discovery, classes, or health.

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 context 'Use this to understand what feeds data into the CMDB', but does not explicitly mention when not to use it or alternatives. However, no sibling tool directly duplicates this function, so the guidance 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral context by explaining the return structure (fields) and parameter details. No contradictions, and the description complements the annotations 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?

The description is concise, uses a clear structure with an initial summary followed by Args and Returns blocks. Every sentence adds value; no redundant or vague statements.

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 that an output schema exists (context signals), the description still summarizes the return fields sufficiently. It covers all necessary aspects for a list tool: what it lists, filtering, pagination, and return format.

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 0% description coverage (only titles), but the description's Args block explains all three parameters: active_only (default True, filters active), limit (range 1-1000, default 25), offset (pagination). This adds full semantic 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 that the tool lists discovery schedules, specifies the underlying table (discovery_schedule), and gives examples of returned fields (name, status, frequency, IP ranges, CI groups). This clearly distinguishes it from sibling tools like get_discovery_status or get_discovery_errors, which focus on other aspects.

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 an explicit usage suggestion: 'Use this to understand what automated discovery is running and when.' It does not explicitly mention when not to use or alternative tools, but the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds caching (1 hour) and describes return fields, providing valuable context beyond annotations.

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

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

The description is well-structured: a clear summary line, an example, Args, Returns, and a typical workflow. No unnecessary sentences, and the key information is front-loaded.

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

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

Given the simple nature of the tool (list with two parameters) and the presence of an output schema, the description is complete. It covers usage, parameters, return format, and provides workflow guidance.

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 0%, but the description explains both parameters (limit and offset) with defaults and purpose, fully compensating for the lack of 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 explicitly states 'List all relationship types' with a specific verb and resource. It also distinguishes from siblings by mentioning a typical workflow with find_related_cis.

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

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

The description provides a typical workflow (list_relationship_types → find_related_cis) and notes caching behavior, helping agents decide when to use it. However, it does not explicitly exclude alternative tools or situations.

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?

Description adds valuable context beyond annotations: token validity (5 minutes), that no record is created, validation occurs. Does not contradict annotations (readOnlyHint, idempotentHint are consistent).

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-organized: purpose, behavior, prerequisites, workflow, examples, parameter docs. Front-loaded with main action. No superfluous sentences; each section earns its place.

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

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

Given complexity (2 params, 0% schema coverage, output schema exists), description covers everything: prerequisites, workflow, return format (token, table, fields, message), usage constraints. No 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 has 0% description coverage, but description fully explains each parameter: table (CMDB table name), fields (must include 'name', examples, cannot set system fields). This provides critical meaning absent from 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?

Clearly states it's a preview (what: preview CI creation) with specific verb 'Preview' and resource 'creation of a new CI'. Distinguishes from sibling tools like confirm_ci_create by noting it does not create a record and returns a token.

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 prerequisites (call describe_ci_class first, suggest_table if unsure), provides a full typical workflow, and includes multiple examples. Clearly differentiates from confirm_ci_create by explaining the process order.

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?

Reinforces annotations (no changes, read-only) and adds token validity, system field restrictions, and diff behavior beyond what annotations provide.

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

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

Well-structured with intro, prerequisites, workflow, examples, and args/returns. Concise 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?

Complete coverage: explains return schema, examples cover common cases, and distinguishes from siblings. No gaps given output schema exists.

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 0% schema coverage, description fully explains each parameter: sys_id, table, fields with examples and restrictions on system fields.

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 previews changes to an existing CI before applying them, without making changes. It uses specific verbs and distinguishes from sibling confirm_ci_update.

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 prerequisites (use search_cis or get_ci_details), typical workflow, token expiration, and provides multiple examples showing when to 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds context about security blocking of server-side scripts and the behavior of the display_value parameter, which enriches the agent's understanding without contradiction.

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

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

The description is well-organized into sections: purpose, security note, examples, and parameter details. Every sentence adds value. It is front-loaded with the core purpose, and examples are clearly formatted. 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's complexity (6 parameters, raw query, security nuance), the description is complete. It explains all parameters, the return structure (even though an output schema exists), and security constraints. No gaps remain.

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 0%, meaning the description must compensate. It does so thoroughly: explains each parameter's purpose, provides examples for encoded_query, lists default fields, defines range for limit and offset, and details display_value modes with usage advice.

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 'Execute a raw encoded query against any CMDB table.' This provides a specific verb and resource, clearly distinguishing from sibling tools like 'search_cis' or 'count_cis' by emphasizing the raw, direct query approach.

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 notes that this is for advanced users who know ServiceNow encoded query syntax, and warns that server-side scripts are blocked. However, it does not directly compare with alternatives like 'search_cis' to indicate when to use one versus the other.

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 details behavioral traits beyond annotations: it clears cached data, forces re-fetch on next access, and specifies what is cleared (class hierarchies, field definitions, etc.). No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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: first sentence states action, second details scope, third provides use case, and final line mentions return value. Each 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?

For a zero-parameter tool with an output schema, the description is complete. It explains the return value ('JSON object confirming the cache was cleared') and the effect on future operations. No 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?

There are no parameters, so the description does not need to add parameter guidance. Baseline score of 4 is appropriate as schema coverage is 100% and no params exist.

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

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

The description uses a specific verb 'Clear' and identifies the resource as 'in-memory metadata cache'. It is distinct from sibling tools, which include various retrieval and analysis tools, none of which share this cache-clearing function.

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

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

The description explicitly states when to use this tool: 'after making schema changes in ServiceNow'. It does not list exclusions or alternatives, but given the unique purpose, this is sufficient 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?

The description adds significant behavioral context beyond the annotations (readOnlyHint, destructiveHint, idempotentHint): it explains name filtering uses STARTSWITH for performance, pagination details (next_offset, has_more), return format (count, records, total_count), and display_value behavior (raw vs display vs both). No contradictions with annotations.

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

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

The description is well-structured with a summary, examples, parameter list, and return section. It is somewhat lengthy but all information is relevant and front-loaded. A minor improvement could be tightening the parameter descriptions.

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 9 parameters, an output schema, and the tool's complexity, the description covers all necessary details: parameters, return format, display options, and pagination. It is self-contained and enables correct invocation without needing additional 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 description coverage is 0%, so the description fully compensates by documenting all 9 parameters with defaults, valid values (operational_status codes explained), behavior (name_filter STARTSWITH, limit range 1-1000), and detailed display_value explanation with examples. This adds substantial 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 searches CMDB configuration items with structured filters, building an encoded query. The typical workflow differentiates it from other CI tools like get_ci_details, but does not explicitly contrast with similar search tools like query_cis_raw or count_cis.

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

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

The description provides a typical workflow (suggest_table → search_cis → get_ci_details → get_ci_relationships) and examples, giving clear context for when to use this tool. However, it does not explicitly state when not to use it or name alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds: queries specific tables, returns confidence scores, best_match flag, pagination. 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: summary, details, usage guidance, examples, args. Approximately 200 words, front-loaded with purpose. 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 output schema exists, description covers purpose, when to use, behavior, parameters, return format (JSON with suggestions, confidence, best_match). Complete for the tool's functionality.

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 has 3 params with 0% description coverage. Description explains description with examples, limit (1-1000), offset (pagination). Could be more explicit about offset usage, but adds significant value.

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

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

Description clearly states the tool suggests CMDB tables based on natural language. It uses specific verb 'suggest' and resource 'CMDB table', and distinguishes from sibling tools that query CIs or manage configurations.

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

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

Explicitly says when to use: when unsure which CMDB table to query. Includes examples and notes about vague descriptions. Could mention alternatives for known tables, but overall clear.

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