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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states it analyzes and returns findings, but fails to mention whether it is read-only, has side effects, requires specific permissions, or produces irreversible changes. The description is insufficient for an agent to understand the tool's behavioral footprint.

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

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

The description is concise with two sentences and front-loads the core purpose. However, it could be slightly more informative without being verbose. Still, it earns a high score for minimal wordiness.

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, no output schema, and many sibling tools, the description lacks completeness. It does not explain the output format, severity levels, or how to use parameters like analysis_depth. The agent would struggle to invoke this tool effectively without 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 only 44%, meaning 5 out of 9 parameters lack descriptions in the schema. The tool description adds no parameter-level information beyond what is in the schema. It does not explain the meaning or impact of analysis_depth, max_script_length, or other parameters, leaving the agent with incomplete understanding.

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

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

The description clearly states the verb 'analyze' against 'widget performance' and specifies distinct analysis areas (code patterns, transaction logs, provider usage). It mentions the return type (findings with severity). This effectively distinguishes it from sibling tools that involve downloading or managing.

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

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

No guidance on when to use this tool versus alternatives. With over 20 sibling tools including audit_local_sources, sn_query, and various diagnostic tools, the description fails to provide any usage context or exclusion criteria.

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

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

With no annotations, description must bear full behavioral disclosure. It describes outputs but does not clarify if the tool modifies sources, error behavior, or performance characteristics. Lacks detail on side effects or safety profile.

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

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

Two-sentence description is concise and front-loaded with purpose and key outputs. 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?

Description covers basic purpose and outputs but lacks detail on report content, cross-ref graph specifics, and dead code detection scope. Given no output schema and simple parameters, more completeness would be beneficial.

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

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

Schema coverage is 100% and parameter descriptions are present. Description does not add meaning beyond the schema; it provides context that source_root is a download output dir, but that's already in the schema. Baseline 3 is appropriate.

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

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

Description states specific verb 'Analyze' and resource 'downloaded sources', and lists deliverables: cross-ref graph, dead code, HTML report. It distinguishes from siblings by noting 'locally (no API)', making purpose clear.

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 mentions 'locally (no API)', implying use after downloading, but does not specify when to use this tool versus siblings like query_local_graph or extract_table_dependencies. No explicit guidance on prerequisites or alternatives.

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

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

No annotations provided, so description carries full burden. It discloses that refresh fast-forwards clean local files from server while keeping edits. Also mentions verdict returns counts only. Does not detail network usage or permissions, but main behavioral traits are covered.

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

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

Description is a single sentence that conveys the main purpose and two key modes. It is front-loaded and avoids redundancy, though slightly dense. Every part adds information.

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

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

No output schema, so description must inform about return values. It describes verdict mode output ('verdict + changed-line counts') but does not describe normal diff output (presumably unified diff). Missing details on context_lines effect and overall structure. Adequate but incomplete.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning beyond schema: clarifies that path behavior differs by type (file→diff, root→summary), explains verdict and refresh modes, and usage of compare_to. This adds value to the schema descriptions.

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

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

Description clearly states the tool diffs local edits vs remote or a compare_to root, with specific modes for verdict and refresh. The verb 'diff' and resources are explicit, and it distinguishes from siblings (no direct diff sibling).

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 guidance for different parameter values (verdict=True for status-only, refresh=True for fast-forward, compare_to for offline diff). It doesn't explicitly state when not to use or compare to siblings, but context shows no similar 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?

With no annotations, the description must carry the full behavioral burden. It only says source is downloaded to disk; it does not mention long-running/background behavior, where files are written, how resume interacts with prior runs, or whether any instance state is modified.

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 very short and front-loaded with the essential action. Minor redundancy in 'FULL/all' and the cryptic 'not portal' phrase are the only detractions.

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

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

For a tool with 14 parameters, no annotations, and no output schema, this description is far too thin. It does not explain invocation flow, background polling, output location, or parameter interactions, so an agent would struggle to call it correctly beyond providing the required scope.

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 only 57%, so the description should compensate for undocumented parameters. It only repeats that scope is required, which the schema already states, and provides no help for the six undocumented parameters.

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

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

The description states a specific action ('download ... source of an app scope to disk') and defines the scope granularity ('all groups+deps'). It stops short of a 5 because 'not portal' only hints at differentiation from download_portal_sources without explicitly naming the alternative scope.

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

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

'Step 1' gives weak workflow context, but the description never states when to choose this tool over alternatives or when not to use it. 'not portal' is a vague exclusion rather than actionable guidance.

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

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

With no annotations provided, the description carries the full behavioral burden and largely fails: no mention of auth/permission requirements, no indication of what saved_path or ResourceLink actually are, no disclosure of whether many-attachment records list or fetch, and no default-path expectations despite the schema defaulting to ./temp/<instance>/attachments/.

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 short sentences, appropriately sized and front-loaded with the core action. However, the second sentence spends its length on undefined concepts instead of earning its place with usable detail.

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 7-parameter tool with no annotations and no output schema, the description is far too thin. It omits the sourcing model (table+record vs attachment_sys_id), the list-vs-download behavior, and what the caller receives, none of which are covered by structured fields.

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

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

Schema coverage is 71% and the schema itself documents record, filename, output_dir, download_all, and attachment_sys_id well. The description adds no parameter meaning and instead introduces 'saved_path' and 'ResourceLink' — terms that correspond to no schema property, so it confuses rather than informs.

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?

States a specific verb+resource (download attachments), but never says from where (ServiceNow records) or which attachments beyond a vague 'attachments'. It competes with siblings like export_record_xml and download_app_sources without any distinguishing scope, leaving the agent to infer from the schema that this is record-attachment retrieval.

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 second sentence gestures at local-vs-remote usage ('Use saved_path locally; read the ResourceLink remotely'), but neither term maps to any parameter or sibling tool, so it gives no actionable when-to-use guidance. It also never mentions the download_all/attachment listing branch as a selection criterion.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description is very minimal, only hinting at targeted download behavior. It does not disclose whether downloads are destructive, authentication needs, rate limits, or any other behavioral traits.

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

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

The description is very concise with two short sentences. The first sentence is vague, and the second provides a contrast with a sibling and a parameter hint. While brevity is good, it sacrifices clarity and completeness. The structure is front-loaded but not efficient in conveying key information.

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

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

Given the complexity of 14 parameters, no output schema, and no annotations, the description is severely incomplete. It fails to explain default behaviors, the effect of boolean flags, what the output looks like, or any usage context. The tool is not adequately described for an AI agent to use it 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 only 36%, meaning most parameters lack schema descriptions. The tool description adds minimal value by hinting that widget_ids specifies a single widget. For other parameters like scope, output_dir, incremental, reconcile_deletions, the schema already has descriptions, but the tool description does not add further meaning. The remaining 9 parameters with no schema descriptions receive no help from the tool description.

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 'Targeted portal widgets/providers' which, combined with the name, implies downloading specific widgets. It distinguishes from 'download_app_sources' for whole app downloads. However, the verb 'download' is not explicitly stated in the description, relying on the name.

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

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

The description mentions when to use this tool (targeted) versus download_app_sources (whole app), providing one key distinction. However, it does not provide any other usage guidance, such as prerequisites, when not to use it, or how to choose among the many sibling tools.

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

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

With no annotations, the description bears the full burden of disclosing side effects. It mentions 'Issues an origin cert' (a potential side effect) and 'Read saved_path' (unclear output behavior), but it does not explain whether the operation is destructive, whether it writes files, or what the origin certificate implication is. This is too vague.

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 short (three sentences) and front-loads the main purpose, but 'Read saved_path' is cryptic and does not earn its place without further context. It is concise but not effectively structured, as the last sentence is confusing.

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 5 parameters, no required ones, no output schema, and no annotations, the description leaves too much ambiguity about how to invoke the tool. It does not clarify the roles of the parameters, the 'origin cert' behavior, or what 'saved_path' refers to. A more complete description is needed for practical use.

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

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

Schema coverage is 80% (4 of 5 parameters described), so the schema carries the meaning. The description does not add parameter-specific detail; in fact, it references 'saved_path' which is not a parameter, potentially confusing the agent. Baseline 3 is appropriate because the schema covers most parameter semantics.

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

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

The description states a clear action ('Build deploy XML') on a specific resource ('the LIVE server') and adds a distinguishing constraint ('the only legal source') that separates it from local/alternative tools. However, it does not name sibling tools, so it falls just short of a 5.

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

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

The phrase 'the only legal source' gives implicit guidance that this tool should be used for deploy XML from live, not local sources. But it does not explicitly mention alternatives or when not to use it. 'Read saved_path' is an instructional hint but unrelated to usage context.

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

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

No annotations are provided, so the full burden falls on the description. It does not disclose if the tool is read-only, performance implications, required permissions, or the format of the output. The term 'dependency graph' is vague and does not explain what response to expect.

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

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

The description is a single sentence, making it concise, but it is too brief given the tool's complexity (10 parameters). It lacks structure and does not front-load critical information.

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

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

With 10 parameters, no annotations, and no output schema, the description is severely incomplete. It does not explain the output format, scope-wide vs. widget-specific behavior, or limitations. The tool is underspecified 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 very low (20%), with only scope and widget_id having descriptions. The description adds no extra meaning for the remaining 8 parameters, such as include_loose_literal_scan or max_records_per_source. With low coverage, the description should compensate but fails to do so.

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

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

The description clearly states it extracts a 'GlideRecord table dependency graph' from server scripts like Script Includes, Business Rules, and widgets. The mention of 'widget_id' hints at a specific scope. However, it does not differentiate from sibling tools like sn_discover or query_local_graph, which may have overlapping functionality.

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

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

The description provides minimal guidance: it mentions passing a widget_id for a single widget, but omitting it implies a scope-wide scan. There is no explicit when-to-use or when-not-to-use, nor any comparison to alternative tools listed as siblings.

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

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

With no annotations, the description must fully disclose behavior. It mentions 'Metadata only' and 'count_only first' but lacks details on side effects, auth, rate limits, or pagination. Inadequate for a tool with 9 parameters.

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

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

Two sentences, front-loaded with purpose, no wasted words. Highly 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?

Given 9 parameters, no output schema, and no annotations, the description is too sparse. It lacks information on return structure, error handling, and detailed behavior for a complex tool.

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

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

Schema coverage is 89%, so baseline is 3. The description does not add meaning beyond what the schema provides for individual parameters; it only gives overall context.

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 developer's recent changes across portal tables' with a specific verb and resource, and adds 'Metadata only' to clarify scope. However, it does not explicitly differentiate from sibling tools.

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

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

Provides some guidance with 'use count_only first' implying a workflow, and 'Metadata only' hints at when to use. But no explicit when-not-to-use or alternatives among siblings.

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

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

No annotations are provided, so the description bears full responsibility. It only discloses a maximum of 20 rows, but omits other behaviors like read-only nature, auth requirements, rate limits, or pagination behavior (despite having offset parameter). The description is minimally transparent.

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 (two sentences), front-loads the verb and resource, and avoids fluff. However, it could be better structured to clearly list log types and constraints. Overall, it earns its place without being verbose.

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 18 parameters and no output schema or annotations, the description is incomplete. It does not explain return values, how parameters interact, or error conditions. The schema covers parameter details but lacks overall context, making it insufficient 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 description coverage is 67%, so many parameters are already documented. The tool description adds no additional meaning beyond the schema; it only mentions log_type. With high coverage, the baseline of 3 is appropriate as the description does not compensate for uncovered parameters.

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

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

The description clearly states the tool queries ServiceNow logs and lists log types (system/journal/transaction/background). It specifies the resource and action, but does not differentiate from sibling tools like sn_query or sn_aggregate, which could also query log data. The purpose is clear but lacks sibling distinction.

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 no guidance on when to use this tool vs alternatives. It mentions a max row limit, but does not explain contexts (e.g., real-time vs historical) or when not to use it. No explicit when/when-not information is given.

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

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

Discloses that it returns body and a 'complete' flag for truncated preview, but omits details on permissions, error handling, and the effect of max_field_length on truncation.

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

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

Two sentences effectively convey the purpose and a key behavioral detail without 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?

Adequate for a simple retrieval tool but lacks details on parameter effects, error responses, and how to interpret the 'complete' flag.

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

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

Schema covers 67% of parameters with descriptions; the tool description adds nothing about parameters and does not compensate for the missing max_field_length description.

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 one source record by name/sys_id, with examples (SI/BR/widget), distinguishing it from more specific sibling tools like get_widget_instance or get_page.

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

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

No guidance on when to use this tool versus alternatives; the description only states what it does without indicating appropriate contexts or exclusions.

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

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

No annotations exist, so description carries full burden. It discloses the read-only nature (get/list) and output format (layout tree), but lacks information on error handling, permissions, or rate limits. Adequate but not detailed.

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

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

Two sentences with no redundancy. The first sentence front-loads the action and key filtering methods. Every word 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 5 parameters and no output schema, the description covers the main parameter and output type. It lacks details on pagination (limit/offset) and the query parameter. Sufficient for a simple tool but could be more complete.

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

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

Schema coverage is low (20% for page_id). The description adds meaning by explaining that page_id accepts sys_id or URL path and toggles between detail and list mode. However, other parameters (limit, query, offset) are not elaborated.

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: getting or listing portal pages by URL path, title, or sys_id, and returning a layout tree with widget placements. It distinguishes itself from sibling tools that deal with widgets, code, or other entities.

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 when to use (to retrieve page layout), but does not explicitly mention when not to use or provide alternative tools for similar tasks. No exclusions or guidance on context.

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

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

No annotations are present, so the description carries the full burden. It discloses a key behavioral trait ('Returns full body by default' and 'Never chunk for analysis'), which is valuable. However, it omits details like response format, error conditions, or required permissions, leaving gaps for a 6-parameter tool.

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

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

Two sentences with front-loaded action. No wasted words. However, the brevity sacrifices important details, making it efficient but slightly under-informative.

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 6 parameters, no output schema, and no annotations, the description is too sparse. It does not explain return values, error handling, or integration with other tools, leaving the agent under-informed for effective 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?

Schema description coverage is 50%; description adds minimal value beyond what the schema already provides. The description only implicitly covers 'fields' via 'Fetch widget/provider/SI fields', but does not explain 'table', 'sys_id', or 'script_offset' beyond what is in the schema. For parameters without schema descriptions, the description is silent.

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 specifies the action ('Fetch') and resource ('widget/provider/SI fields'), and distinguishes default behavior ('full body by default'). While not explicitly differentiating from all siblings, the description implies this tool is for fetching code fields, which is a distinct purpose among the listed siblings.

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?

Gives a clear negative guideline ('Never chunk for analysis'), but lacks positive when-to-use context or direct comparison to alternatives. The agent is not told when to prefer this over siblings like search_server_code or get_widget_instance.

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

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

No annotations provided, and the description does not disclose behavioral traits such as read-only nature, required permissions, or side effects. For a fetch operation, it should at minimum indicate it is a read action.

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

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

The description is a single concise sentence with no wasted words. However, it could be more structured (e.g., bullet points) to improve scanability.

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 3 parameters, no output schema, and no annotations, the description is incomplete. It does not explain the response format, error conditions, or how the bundle components relate, making it insufficient for complex tool usage.

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

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

Schema coverage is 33% with only widget_id described. The description does not explain the boolean parameters (include_providers, include_dependencies) or their defaults, leaving ambiguity.

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 fetches a full widget bundle including HTML, scripts, providers, and dependencies, and positions it as an analysis starting point. However, it does not explicitly distinguish from sibling tools like 'get_widget_instance'.

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

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

No guidance on when to use versus alternatives (e.g., get_widget_instance). Only mentions 'analysis starting point' which implies initial investigation but lacks explicit when/when-not instructions.

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

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

No annotations are provided, so the description alone must disclose behavioral traits. It only states that the tool returns data (column, order, config) without mentioning side effects, authorization requirements, rate limits, or destructiveness. For a read operation, this is minimally acceptable but incomplete—e.g., it does not confirm that the operation is non-destructive or requires certain permissions.

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

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

The description is concise at two sentences, front-loaded with the action and key details. It avoids unnecessary fluff. It could be slightly more structured, but it effectively communicates the core purpose without verbosity.

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, no output schema, and no annotations, the description is adequate but not thorough. It covers the primary functionality and filter options but lacks details on parameter defaults (e.g., limit default 20), pagination behavior, error cases, or what the returned data structure looks like. For a simple retrieval tool, this is minimally viable but leaves room for improvement.

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 60% (3 of 5 parameters have descriptions). The description adds context for page_id and widget_id by stating 'Filter by page or widget,' and clarifies instance_id's role in list vs. detail mode. However, limit and offset remain undocumented in both the schema and description, leaving their purpose implicit. The description adds moderate value beyond the schema.

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

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

The description clearly states the action ('Get'), the resource ('widget instance placement'), and what it returns ('column, order, and config'). It also mentions filtering by page or widget, making the tool's purpose unambiguous and distinct from sibling tools like get_widget_bundle or analyze_widget_performance.

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 basic clue on usage ('Filter by page or widget') but does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. Sibling tools such as get_widget_bundle or analyze_widget_performance could serve different purposes, but no comparison is made. More guidance would improve clarity.

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

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

With no annotations, the description carries the full burden of behavioral disclosure but only states the basic action. No details about side effects, authentication, or output behavior are provided.

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

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

The description is a single sentence of 11 words with no filler. Every word earns its place, making it concise and effectively 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 lack of output schema and complexity, the description is minimally adequate. It states the purpose but omits details like return format or package identification, which could improve completeness.

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

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

The tool has zero parameters, so the baseline is 4. The description adds meaning by specifying that it lists available packages and the currently loaded one, which is helpful context beyond the empty 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 lists tool packages and the currently loaded one, using a specific verb and resource. However, it does not differentiate from sibling tools that also perform listing 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?

The description provides no guidance on when to use this tool versus alternatives. No context or exclusions are mentioned.

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

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

With no annotations, the description carries the transparency burden and does disclose the mutation/edit nature, the publish confirmation requirement, and the clone behavior of add_branch. However, it omits side effects, browser-auth requirements for writes, and reversibility details; some of this is available in the schema's action property description but not in the tool description itself.

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 compact and front-loaded with the resource and main purpose. The parentheticals are dense but efficient; there is almost no filler.

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?

This is a high-complexity tool with 27 parameters, no output schema, and no annotations. The description covers only a small subset of operations and does not explain return values, auth constraints, or typical publish/edit flows, so an agent would need to infer much from the 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 only 52%, so the description should compensate, but it only clarifies a few parameters: action='publish', confirm='approve', confirm_publish, and add_branch's clone behavior. The remaining 27 parameters, including filters, paging, and include flags, receive no descriptive help 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 identifies the resource as Flow Designer and enumerates specific capabilities: reading/editing action inputs, trigger/branch conditions, cloning branches via add_branch, and publishing. It is reasonably specific and distinctive from siblings like manage_workflow, though 'read/edit' is a generic verb pairing rather than a precise statement of what the tool manages.

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?

Usage is implied by the resource name and the listed operations: if an agent needs to read or edit Flow Designer flows, this is the tool. No explicit alternatives or when-not-to-use guidance is given, though the publish confirmation caveat provides some task-specific direction.

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

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

No annotations are provided, so the description must fully disclose behavior. It claims 'CRUD' but only lists list/get actions, which is contradictory and misleading. The required confirm parameter suggests destructive operations, yet only read actions exist. No details on side effects, authorization, or rate limits are given.

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 brief (one sentence), which is concise but lacks structure. It front-loads the purpose but omits important details. Given the tool's complexity, more focused information would improve usability.

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 7 parameters, no output schema, and a complex domain, the description is severely incomplete. It doesn't explain return format, pagination behavior, query filter syntax, or how count_only works. The discrepancy between CRUD and actual actions further reduces completeness.

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

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

Schema coverage is 14% (only service has a description). The description adds that list/get are used to find sys_ids and that confirm must be 'approve', which provides some constraint. However, parameters like limit, offset, query, count_only are not explained at all.

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 identifies the tool as managing Scripted REST services and resources, and specifies using list/get to find sys_ids. It clearly indicates the resource type (sys_ws_definition/sys_ws_operation), distinguishing it from sibling tools. However, the mention of 'CRUD' is misleading since only list and get actions are available.

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 list/get to find sys_ids, providing some usage guidance. It also notes the confirm parameter must be 'approve', implying a safety check. However, it does not explain when to prefer this tool over siblings 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?

Without annotations, the description carries the full burden. It mentions 'confirm='approve'' but does not disclose side effects (e.g., whether create/update/delete are destructive), permission requirements, or behavior of 'execute'. The tool's mutating capabilities are implied but not explained.

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

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

The description is a single concise sentence, but it omits essential details. While brevity is positive, the lack of structure (e.g., no bullet points or sections) reduces its utility.

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, 2 required, and no output schema, the description is inadequate. It fails to explain parameter roles, return types, or behavior for each action. The tool is complex (CRUD+execute) but the description treats it minimally.

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 only 22%, leaving most parameters undocumented. The description adds no meaning beyond the schema, e.g., it doesn't explain 'query', 'active', or 'script_include_id'. It only hints at the 'confirm' parameter 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?

The description lists all actions (list, get, create, update, delete, execute) and specifies the target table (sys_script_include), making the purpose clear. However, it does not distinguish from sibling tools like manage_scripted_rest or manage_workflow.

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

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

No guidance is provided on when to use this tool versus alternatives, no prerequisites, and no instructions on when not to use it. The description only lists actions without context.

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

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

No annotations are provided, so the description bears full responsibility for disclosing behavioral traits. It mentions CRUD and link/unlink, implying mutation, but gives no details on side effects (e.g., what changes are persisted, whether dependencies are overwritten or appended, permission requirements). The 'save_to_disk' parameter hints at file writes but is not explained. This leaves significant behavioral ambiguity.

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

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

The description is a single sentence plus a parenthetical hint—extremely concise with no filler. It front-loads the core purpose (CRUD + link/unlink) and immediately provides actionable guidance ('Use action=list first'). Every word 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?

Despite the tool's complexity (14 parameters, 6 action types, 3 target types), the description is too brief to equip an agent with full understanding. It omits relationships between parameters (e.g., when to use widget_id vs widget_ids), the effect of each action on data, and output behavior. The lack of an output schema exacerbates this. Agents would likely struggle to use this tool correctly without 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 71% (10 of 14 parameters have descriptions). The description adds a usage hint for 'action' and 'confirm' but does not significantly elaborate on parameter meaning beyond the schema—e.g., it doesn't explain how 'depth' affects chain reading or how 'scope' filters. This is adequate but not enhanced.

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 performs CRUD and link/unlink operations for widget providers and dependencies. The verb 'manage' is broad but the description specifies the exact resource scope (Angular providers & CSS/JS dependencies). While it doesn't explicitly differentiate from sibling tools, the unique combination of CRUD and link/unlink for a specific resource makes the purpose clear.

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 'Use action=list first for sys_ids' and mentions the required confirm parameter value. This provides a basic workflow hint but does not specify when to use this tool versus alternatives, nor does it describe prerequisites or conditions for each action type. The hint is useful but incomplete for guiding the agent's decision.

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

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

No annotations provided, so the description must convey behavioral traits. It only mentions it is legacy and that confirm='approve', but does not disclose whether actions are read-only, what they return, or any side effects. Essential behavior is missing.

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

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

The description is very short, which is concise, but it omits critical information about actions and parameters. Brevity comes at the cost of completeness.

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

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

Given the complexity (9 parameters, no output schema, low schema coverage), the description is vastly incomplete. It lacks explanations for actions, query parameters, pagination, and return values, making it insufficient for an AI agent to invoke 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 only 11% (only version_id has a description). The description only adds context for the confirm parameter, leaving 8 parameters unexplained. This is insufficient for effective use.

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 identifies the tool as targeting the legacy workflow engine (wf_workflow/wf_activity) and distinguishes it from the Flow Designer tool (manage_flow_designer). However, it does not explicitly state the actions (list/get_activities) available in the input schema, so some ambiguity remains.

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 'LEGACY Workflow engine ONLY' and directs to use manage_flow_designer for most flows, giving a clear when-to-use vs when-not-to-use. Also notes that confirm must be 'approve', which is a required parameter.

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 states it's offline and uses local files (0 API), indicating no network calls. However, it does not confirm read-only behavior, permissions needed, or what the 'audit graph files' entail. Without annotations, the description carries full burden and is minimal.

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

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

The description is a single sentence, concise and front-loaded with the core purpose. Every word is relevant and no repetition. However, it could benefit from slightly more structure, like separating the overall purpose from parameter details.

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

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

The description does not explain return values or output format, which is a gap since there is no output schema. It also does not clarify what 'audit graph files' are or how they are generated, leaving important context missing for an offline tool.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description lists possible values for action (uses|used_by|page|impact), but this is already in the schema description. It adds marginal value beyond what structured fields provide.

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 provides offline dependency/impact answers from audit graph files, listing specific actions (uses, used_by, page, impact). It distinguishes from sibling tools like search_server_code or sn_query which are online. However, the term 'audit graph files' is somewhat vague and could be more precise.

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

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

No explicit guidance on when to use this versus other tools, such as when offline analysis is preferred over online queries. The description does not mention prerequisites or alternatives, leaving the agent to infer usage from context.

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

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

No annotations are provided, so the description bears the burden of behavioral disclosure. It mentions 'True regex' and 'offsets+context', indicating it returns position and surrounding text, and that it treats input as regex. However, it does not disclose destructive potential (likely read-only), performance considerations, or authentication requirements. The description adds some value but is incomplete.

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 extremely concise: two sentences that front-load the core functionality. Every sentence provides essential information with no wasted words. It is appropriately sized for a tool with many parameters.

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 19 parameters, no output schema, and no annotations, the description is too minimal. It does not explain the output format, pagination behavior, or how filters (e.g., updated_by, updated_after) work. A more complete description would include usage examples or output details.

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 parameter schema has 68% coverage, meaning some parameters are described in the schema. The description adds no parameter-specific meaning; it only gives an overview. With moderate coverage, the description should compensate for missing parameter descriptions but does not. It does not explain any parameter beyond what is in the schema.

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

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

The description clearly states the tool performs 'True regex over portal code (widget/provider/SI)' and provides 'offsets+context'. It distinguishes from sibling 'search_server_code' by noting it is for keyword search, implying this tool is for regex search. The verb 'search' and resource 'portal code' are specific.

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

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

The description mentions an alternative ('Server-table keyword search: search_server_code') but does not explicitly state when to use this tool vs alternatives. It implies regex search over portal code, but lacks clear context for when to choose this over other search tools. No exclusions or prerequisites 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?

No annotations exist, so the description carries full burden. It only says 'Fast keyword search' but fails to disclose read-only nature, authentication requirements, rate limits, or what the output contains. The behavioral traits are largely undisclosed.

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 efficient sentences, front-loading the core purpose and immediately linking to the sibling tool. Every word adds value; no filler.

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

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

Despite no output schema, the description omits any mention of return values (e.g., snippets, match structure). It also does not address pagination, limits on scope, or other operational details expected for a search tool with six parameters.

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

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

Schema description coverage is 50%, with half of parameters (e.g., limit, query, max_snippet_length) lacking descriptions. The tool description adds no extra parameter meaning beyond listing code types; it does not compensate for the missing schema explanations.

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

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

States it performs 'Fast keyword search across 22 server-side code types' with examples (SI/BR/ACL), and explicitly names the sibling tool for portal regex search, clearly distinguishing its scope.

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

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

Provides a direct pointer to the alternative tool (search_portal_regex_matches) for portal regex searches, implying when to use this vs that. However, it does not give explicit when-not-to-use conditions or prerequisites.

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

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

No annotations provided, so description carries the burden. States it returns stats without fetching records (read-only implication), but does not disclose required permissions, rate limits, or other behavioral traits like whether grouping affects the result structure.

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

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

Single sentence that efficiently conveys the tool's purpose and key feature (no record fetching). No wasted words.

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

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

The description is minimal but covers the core functionality for a simple aggregate tool. Lacks details on output format, error handling, or complex use cases, but given the absence of an output schema, extra context on return structure would be helpful.

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

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

Schema coverage is 60% (descriptions for field, aggregate, group_by). Description adds no extra meaning beyond summarizing aggregate types; it does not explain the 'query' or 'table' parameters beyond the schema. Baseline 3 is appropriate as schema already provides partial 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?

Clearly states the verb 'Run' and resource 'aggregate on any table' with specific operations COUNT/SUM/AVG/MIN/MAX and optional group_by. Distinguishes from sibling tools like sn_query by specifying statistical aggregation without fetching 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?

Implies usage for statistics without fetching records, but lacks explicit when-to-use versus alternatives (e.g., sn_query for records). No exclusions or prerequisites mentioned.

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

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

No annotations provided. The description does not disclose any behavioral traits such as read-only nature, performance impact, or side effects. For a tool that searches data, basic transparency on safety is missing.

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

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

The description is a single, well-structured sentence that front-loads the purpose and lists key return fields. No wasted words; every part earns its place.

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

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

Given the simplicity of the tool (2 parameters, no output schema, no annotations), the description is adequate but not rich. It could mention pagination, ordering, or that results are limited to tables. Without output schema or annotations, the description carries the burden and is minimally complete.

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

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

Schema coverage is 50% (keyword described, limit not). The description adds value by stating that keyword searches table names and labels, compensating partially for the missing description of limit. However, limit's purpose and default behavior are not explained.

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 tables by name or label keyword, and lists the return fields (table name, label, scope, parent class). It distinguishes itself from siblings by being a table discovery tool, which is specific among the diverse set of sibling tools.

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

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

No explicit guidance on when to use this tool versus alternatives like sn_query or search_server_code. The description implies its use for table discovery but does not provide context for exclusion or comparison.

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

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

No annotations provided. The description only lists what is checked; it does not disclose whether the tool is read-only, requires specific permissions, has side effects, or how it behaves on failure. Given the zero annotation burden, this is insufficient.

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

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

One sentence of 15 words efficiently lists all check categories. No fluff, no repetition, perfectly 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?

No output schema and no annotations. The description omits what the response looks like, error handling, or return format. For a health check tool, an agent would need to know if the result is structured text, boolean flags, or a summary.

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

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

Schema coverage is 100% with parameter descriptions already present. The tool description adds no additional meaning to the parameters (deep and timeout). Baseline 3 is appropriate as it does not detract nor enhance 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 uses a specific verb 'Check' and lists distinct resources: ServiceNow API connectivity, auth status, Chromium install state, and MCP server version. This clearly distinguishes it from sibling tools like sn_query or manage_script_include.

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

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

No guidance on when to use this tool versus alternatives, no prerequisites, no when-not-to-use context. Agent must infer from the description alone, which lacks contextual advice.

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

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

No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, performance implications, or side effects. A query tool likely reads data, but this is not confirmed.

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

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

Extremely concise: two sentences that front-load the purpose and usage guidelines. No unnecessary words.

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

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

With 8 parameters, no output schema, and no annotations, the description is insufficient. It lacks details on how to construct queries, pagination, return format, or parameter usage, which are critical for correct 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?

Schema description coverage is low (25%). The description adds no parameter explanations beyond what the schema partially provides. It does not compensate for the missing parameter 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 'Generic table query — last resort' specifies the verb (query) and resource (table), and distinguishes from sibling domain tools. It is clear but could be more explicit about the context of 'table'.

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

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

Explicitly states 'last resort' and directs users to prefer domain tools like search_server_code, manage_workflow, manage_flow_designer, providing clear when-to-use and alternatives.

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

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

With no annotations provided, the description carries full burden. It declares 'Read-only' which confirms no side effects, and describes the parsing behavior without ambiguity. This fully discloses the tool's nature and output.

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

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

The description is a single sentence, front-loading the key action ('Parse a ServiceNow URL') and listing output components succinctly. Every word serves a purpose with no redundancy.

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

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

Given the tool has one parameter and no output schema, the description adequately specifies return components (table, sys_id, scope, suggested next tool). However, it does not mention return format, error handling, or invalid URL behavior, leaving minor 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 100% for the single 'url' parameter, so baseline is 3. The description does not add extra detail about URL format or constraints beyond what the schema already provides.

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

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

The description clearly states the verb 'Parse' and the resource 'ServiceNow URL', and specifies the outputs: table, sys_id, scope, suggested next tool. This distinguishes it from sibling tools like sn_query or sn_aggregate which are for querying or aggregation rather than URL parsing.

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?

While not explicitly stating when to use vs alternatives, the description mentions 'suggested next tool' implying guidance. The 'Read-only' tag indicates safe usage. The context is clear enough for a single-purpose tool, but lacks explicit exclusions or prerequisites.

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

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

No annotations are provided, so the description must disclose all behavioral traits. It does not mention whether the operation is read-only, if it has side effects, or any rate limits. The description only states what data is fetched, but not how it behaves.

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

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

The description is a single concise sentence that front-loads the core purpose. It contains no unnecessary words or fluff, though it could be slightly improved by adding a brief note about the optional limit parameter.

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 2 parameters and no output schema, the description reasonably explains what is returned. However, it does not clarify how the 'limit' parameter affects results or if there is pagination, which is important for a data-fetching tool.

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

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

Schema description coverage is 0%, so the description must add meaning for each parameter. It mentions the 'table' parameter implicitly, but the 'limit' parameter is entirely undocumented. The description does not explain the default behavior or constraints of the parameters.

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

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

The description clearly states the action ('Fetch'), the resource ('field names, types, labels, and constraints from sys_dictionary'), and the context ('for a given table'). It distinguishes from sibling tools that perform different operations like querying or aggregating data.

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 no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. An agent receives no context for choosing this over other sibling tools.

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

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

With no annotations provided, the description must convey behavioral traits. It states 'Metadata only, no script bodies', which is a key behavior. However, it does not disclose other important aspects such as read-only nature, required permissions, or potential performance impact, leaving gaps.

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

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

The description is a single, front-loaded sentence that conveys the core purpose and a key constraint. It is maximally concise with no redundant information.

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

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

Given 13 parameters and no output schema, the description is too terse. It does not explain what the output looks like, how results are structured, or how this tool fits with siblings. More detail is needed 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 69%, meaning many parameters already have descriptions. The tool description adds no additional parameter-level guidance beyond 'map relationships'. Baseline 3 is appropriate as the schema handles most of the load.

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

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

The description clearly states the action ('Map widget→provider→route relationships'), which is a specific verb+resource structure. It further clarifies the scope with 'Metadata only, no script bodies', distinguishing it from siblings like search_portal_regex_matches or get_portal_component_code.

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 mapping relationships and excludes script content, but it does not explicitly state when to use this tool versus alternatives (e.g., search_portal_regex_matches for content search). No when-not or alternative tools are mentioned.

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

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

With no annotations, the description carries the full burden. It explains the behavioral difference between preflight and postflight, which adds context. However, it does not disclose side effects (even whether it modifies anything), permissions, rate limits, or return behavior. 'Compare' implies read-only, but that is not explicit.

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

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

The description is a single, tightly worded sentence with no filler. It front-loads the core action and uses compact mode definitions that earn their place. Extremely 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?

The tool has no output schema and no annotations, yet the description does not explain what the tool returns or any prerequisites. While mode semantics are helpful, the description omits potential side effects, workflow context, and result interpretation. It is adequate but leaves gaps for a 4-parameter tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds behavioral meaning to the 'mode' parameter ('would it revert work' vs 'did it land'), which goes beyond the schema's simple 'before import' and 'after import'. Other params are already well-described in the schema.

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

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

The description states a specific verb+resource: 'Compare a deploy XML to the live server.' It further distinguishes itself by defining preflight and postflight modes, which clearly separates it from sibling tools like export_record_xml or query tools.

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

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

The description provides clear guidance for mode usage: 'preflight=would it revert work, postflight=did it land.' This implies when to use each mode (before vs after import). However, it does not name alternative tools or explicitly 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.