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

With no annotations, the description carries the full behavioral burden and explicitly discloses that the operation is 'read-only' and 'bounded'. It also adds useful operational details: 'window_days' defaults to 90 days, 'since' overrides it, and 'limit' is capped by MAX_ROW_LIMIT. It omits auth requirements and per-action effects, but the core safety profile is clearly stated.

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

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

The one-sentence summary is front-loaded and the Args block is compact with no filler. Each line adds parameter semantics or a default/cap that the schema does not provide, making it appropriately sized.

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?

Parameter semantics and the read-only/bounded behavior are well covered, and an output schema exists so return values need not be documented. However, the three action modes are not explained at the semantic level, and there is no guidance on how 'analysis' relates to overlapping siblings, which leaves the description incomplete for tool selection.

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

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

Schema description coverage is 0%, so the description must compensate for all 8 parameters, and it does. Every parameter is explained with allowed values, targets, defaults, or overrides, including the permitted journal fields and the row cap/offset behavior.

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 opening line states a specific operation ('bounded, read-only analysis') over defined resources ('catalog answers or journals'), and the Args section names concrete action modes ('ritm_variables', 'journal_history', 'describe'). This is clear but does not distinguish the tool from siblings such as 'query', 'audit', or the sibling also named 'describe'.

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 given on when to choose this tool over the sibling alternatives or when not to use it. The parameter notes explain mechanics but not the selection context, so an agent must infer usage from the generic word 'analysis'.

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 convey behavioral traits. It indicates read-only operation ('Read attachments') but does not disclose idempotency, authentication needs, rate limits, or side effects. The transparency is adequate but not comprehensive.

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

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

The description is concise, using a clear list format for actions and parameters. Every sentence adds value, and there is no extraneous text.

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

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

Given the tool's complexity (5 parameters, no annotations, output schema exists), the description sufficiently covers the action types and parameter mappings. It does not explain return values (handled by output schema), but could benefit from more context on when each action is appropriate.

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

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

The input schema has 0% description coverage, but the tool description compensates well by explaining each parameter's purpose (e.g., 'sys_id: Attachment sys_id (for get, download)'). This adds significant meaning beyond the raw schema fields.

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

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

The description clearly states 'Read attachments' and enumerates specific actions (list, get, download, download_by_name), making the tool's purpose unambiguous and distinguishing it from the sibling tool 'attachment_write'.

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 via the action parameter but provides no explicit guidance on when to choose this tool over siblings like 'attachment_write' or when not to use it. There is no mention of 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. The description lacks disclosure of side effects (e.g., deletion permanence), permission requirements, or error behavior. It only explains parameter usage.

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

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

The description is concise, front-loaded with the core purpose, and uses a clear bullet-like list for arguments. 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?

The description covers parameter semantics adequately but lacks higher-level context such as success/failure responses or limitations. With output schema present, return values may be addressed externally.

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

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

The description compensates for 0% schema coverage by explaining each parameter's role and conditionally grouping them under upload or delete actions. This adds significant meaning beyond the schema titles.

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

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

The description clearly states 'Write attachments' and specifies two actions: 'upload' and 'delete'. This distinguishes it from sibling tool 'attachment' which likely reads attachments.

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 upload vs delete, nor prerequisites or alternatives. The description only lists parameters without 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?

With no annotations, the description carries full burden. It explains that the tool inspects posture and trail, and warns about performance implications of wide windows. However, it doesn't explicitly state whether the tool is read-only or if it modifies data, though 'inspect' implies read-only.

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

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

Description is well-structured with a brief intro, an important warning, and a clear Args list. It is informative but not overly verbose. Could be slightly more concise by removing redundant 'required for' phrasing, but overall effective.

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

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

Given the complexity (8 parameters, 5 actions), the description covers all necessary usage and constraints. An output schema exists (not shown) which would further help, but the description itself is complete enough for an agent to understand behavior and 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?

Input schema has 0% description coverage, but the description provides detailed explanations for all 8 parameters including the allowed action values, required fields for each action, and constraints like 1..50 for fields_csv and 32-char sys_id. This adds significant meaning beyond the schema.

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

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

Description clearly states 'Inspect ServiceNow audit posture (table/field config) and audit trail.' This is a specific verb-resource combination that distinguishes it from sibling tools like query (which retrieves records) and record_read (reads specific 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?

Provides explicit guidance on when to use the tool and when to be cautious: warns about sys_audit table size, default 90-day window, and advises to override window_days or since only when necessary. Also implicitly differentiates from siblings by focusing on audit trail vs general querying.

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 behavioral burden. It does disclose useful behavioral details: default limit, default search group, and the effect of extended_matching. But it does not state whether the operation is read-only, what each action returns, or any side effects or permissions needed, so transparency is partial.

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 front-loaded with the tool's purpose and then uses a clean Arg list without redundant prose. Each line carries meaningful information, and the formatting is scannable for an agent.

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

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

All parameters are explained and defaults are supplied, and an output schema exists so return-value details are not the description's burden. Minor gaps remain in the semantics of 'list_tables' and 'describe' actions, but overall the description provides sufficient context 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?

The input schema has 0% description coverage, yet the Args block fully documents all six parameters, including allowed action values, defaults, and when each parameter applies. This more than compensates for the schema's lack of descriptions and gives an agent enough to construct valid calls.

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 first sentence states a clear verb and resource: 'Search ServiceNow code or inspect Code Search table coverage.' The action parameter further clarifies three operational modes, making the tool's purpose concrete. It does not explicitly contrast with siblings like 'query' or 'investigate', but the name and core sentence are specific enough.

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

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

The description implies usage context through the action choices and parameter explanations, such as 'term: Search term for action='search'' and 'extended_matching... Set true when the extra context is needed.' However, it never says when to choose this tool over alternatives or when not to use it, leaving the selection guidance mostly implicit.

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

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

With no annotations provided, the description carries the full behavioral burden, and it delivers: it discloses bounded pages, capping, a fixed deny-list for verbose output, the resolved super_class chain for script fields, and default behavior. The read-only nature is implied consistently through 'Return' and 'list' language, and no destructive or surprising side effects are hidden.

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 front-loaded with the core purpose, followed by a tight, well-organized Args list. Each parameter entry earns its place with concrete behavioral detail, and there is no filler or repetition.

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 eight parameters, no annotations, and an output schema; the description covers all parameter semantics, action modes, defaults, edge cases, and return-behavior nuances. The presence of an output schema relieves it from explaining return value shape, and nothing essential for correct invocation is missing.

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 fully explain all eight parameters, and it does. Every parameter is described with its role, allowed values like '*' or 'list_tables', defaults, and mode-specific behavior, adding meaning far beyond the bare schema names and types.

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

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

The description opens with a specific verb and resource: 'Return slim field metadata for a table, or list tables / script fields.' This makes the core purpose clear, and the action modes further clarify behavior. However, it does not explicitly distinguish this tool from sibling tools such as query or record_read, so it stops short of full sibling differentiation.

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 contextual guidance for each action mode, including which parameters are required or ignored for each flow, and how empty vs. explicit values behave. It does not explicitly state when to prefer this tool over sibling alternatives, but the internal usage conditions are strong and actionable.

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 present, the description carries the full safety burden and explicitly declares 'read-only' up front. It also discloses defaults and caps for limit, section_limit, and sections behavior, plus the sys_id/name mutual exclusion, which are meaningful beyond the schema fields.

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 compact, front-loaded docstring: one purpose sentence followed by a parameter-to-action map. No line is redundant; the actionable constraints (mutual exclusivity, defaults, wildcard behavior) are included without fluff.

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

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

For a ten-parameter, six-action tool with no schema descriptions, the description addresses almost all invocation details, and an output schema is available for return values. The main residual gap is that the 'contract' action is named and referenced by 'sections' but never defined, which leaves some ambiguity for an agent deciding to use it.

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

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

Schema description coverage is 0%, and the description compensates completely by defining the action enum, which parameter applies to which action, value encoding, defaults, and the sys_id/name exclusivity constraint. Every parameter receives semantic context that is not visible in the input schema alone.

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

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

The opening line names a specific action and resource: 'Inspect Flow Designer flows, triggers, and value blobs (read-only).' The args list clarifies it is a multi-action utility, but it does not explicitly contrast itself with sibling tools such as query, record_read, or describe, so sibling differentiation is left to the reader.

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 Args section associates each parameter with the action in which it is used (e.g., 'value: gzip+base64+JSON blob to decode (decode_values)'), which implies the appropriate invocation pattern. It never states when to prefer this tool over sibling alternatives or when not to use it, leaving the selection criteria implicit.

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

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

'There are no annotations, so the description carries the full burden of behavior explanation. It does disclose the mode-based behavior and parameter applicability, which is useful. However, it does not describe the effects of running an investigation, whether it creates or modifies state, what the output looks like beyond the output schema, or any side effects or failure conditions.'

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 single-sentence purpose, followed by a tight Args block that covers all four parameters without redundancy. Every sentence contributes operational information.

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

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

For a four-parameter tool with no annotations and 0% schema coverage, the description is largely complete: it provides action values, investigation name options, and parameter-specific rules. The main remaining gap is the expected inner structure of the 'params' JSON string for 'run', which is left to the caller to know. The existence of an output schema reduces the need to document return values, so the overall definition is still quite complete.

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

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

Schema description coverage is 0%, so the parameter burden falls entirely on the description, and it delivers. It explains each parameter in plain language: the accepted values of action, the role of name across modes, that params is a JSON string used only for 'run', and that element_id is a 'table:sys_id' identifier for 'explain'. It even lists available investigation names, making parameter choice actionable.

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 opens with a specific verb and resource: 'Run an investigation or explain a finding,' and then defines three distinct actions: 'run', 'explain', and 'describe'. It clearly maps the tool's scope, though it does not explicitly differentiate itself from siblings like 'describe', 'analysis', or 'audit', which leaves a small ambiguity.

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

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

'The description gives clear action-specific usage context: name is 'required for 'run'', optional as a direct selector for 'explain', and a filter for 'describe'; params is 'run only'; and element_id is 'explain only'. This is strong contextual guidance, but it does not explicitly state when to prefer this tool over alternatives or when not to use it.

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

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

The description discloses the basic read operation but provides no details on authentication requirements, potential rate limits, or any side effects. With no annotations, more behavioral context would be helpful, but the simplicity of a list operation mitigates the gap.

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 with no unnecessary words. It is front-loaded with the action and resource, making it easy to parse.

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

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

Given the simplicity of the tool (no parameters, no annotations, output schema exists), the description is minimally sufficient. However, it could clarify what 'tool packages' and 'tool groups' are or if any preconditions exist.

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

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

The input schema has zero parameters, so schema coverage is 100%. The description does not need to add parameter meaning; the baseline score of 4 is appropriate.

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

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

The description clearly states the action ('List') and the resource ('all available tool packages and their tool groups'). It distinguishes from sibling tools like 'query' or 'record_read' which have different purposes.

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

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

No guidance is given on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer usage solely from the tool name.

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

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

No annotations are provided, so the description carries the full burden, and it does a good job: it discloses that sys_id ignores other filter args except fields and display_values, that aggregate mode returns aggregates instead of rows, that list mode requires fields, and exactly how resolve_labels gets ANDed into the encoded query. It could add permission and max-row-limit specifics, but the core behavioral quirks 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?

A one-line summary is front-loaded, and the Args block that follows is dense but justified: 11 parameters each get behavior that the schema lacks, so every sentence earns its place. It is long because it must be, not because of wasted words.

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

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

For an 11-parameter tool with no annotations and an output schema (so return shapes needn't be explained), the description covers all argument semantics and mode behaviors thoroughly. The remaining gaps are minor: max_row_limit is referenced but never quantified, and the description gives no hint about when to choose this over record_read, so selection across read siblings is left to inference.

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% — the schema provides only titles, types, and defaults — so the description must compensate, and it fully does. All 11 parameters get precise semantics: prefixes such as '-' for descending order_by, comma-separated aggregate/group_by syntax, the fields projection rules, and the interaction between sys_id, fields, and display_values. This is exactly the compensation a 0%-coverage schema requires.

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 opening line 'Read records, aggregates, or a single record from any ServiceNow table' states a specific verb, resource, and three distinct modes, so the tool's job is immediately clear. However, it never distinguishes itself from the sibling record_read tool, which appears to overlap in purpose.

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

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

There is no explicit when-to-use vs. when-not-to-use guidance and no mention of the record_read sibling, so an agent must infer which read tool to pick. Usage context is only implied through argument semantics (e.g., sys_id selects single-record mode, aggregate returns aggregates instead of rows).

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, it discloses key behavior: the token is single-use and consumed on success or failure, indicating idempotency and ensuring the agent understands the token's lifecycle.

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 plus a bullet, no fluff, purpose is front-loaded. 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?

For a simple commit tool with one parameter and an output schema, the description covers the essential behavior and usage. Minor gaps in error details, but overall sufficient.

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

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

With 0% schema description coverage, the description compensates by explaining the preview_token parameter's origin and single-use nature, adding crucial context beyond the schema.

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

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

The description explicitly states 'Commit a previously previewed write', using a specific verb ('commit') and resource ('previewed write'), differentiating it from siblings like 'record_write' which handles previews.

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?

It clearly states to use after a preview with record_write, and specifies the token origin. Though it does not explicitly list when not to use, the context is sufficient.

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

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

With no annotations provided, the description carries the full burden, and it delivers: sensitive fields are masked, script_fields is resolved via sys_dictionary and super_class chain, zero-script-field tables succeed with an empty list, and ambiguous name lookups error. This gives an agent accurate expectations beyond the input schema.

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

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

The description is longer than average but well-organized with a front-loaded purpose sentence and an Args section. The behavioral details about script_fields are relevant and earn their place. Minor redundancy exists because mutual exclusivity is stated both up front and within each parameter, but overall structure is effective.

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

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

For a read tool with no annotations and no schema-level parameter descriptions, this definition covers the key operational context: required/optional parameters, edge cases, return behavior, and integration with a subsequent record_write. The presence of an output schema means return-value structure does not need to be duplicated in the description.

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 fully compensate, and it does. Every parameter is explained: table with examples, sys_id with mutual exclusivity, name with resolution semantics and ambiguity errors, and fields with projection and empty-value behavior. This is a complete parameter contract.

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 first sentence clearly states the verb and resource: 'Fetch a record by sys_id or name from any table.' This distinguishes it from siblings like query, record_write, and describe by specifying a direct record-fetch operation by identifier. The scope is concrete and immediately actionable.

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 invocation context: exactly one of sys_id or name must be supplied, and ambiguous name matches return an error. It explains the relationship to record_write by mentioning script_fields discovery, but it does not explicitly contrast this tool with query or other read-oriented siblings. Still, the usage conditions are unambiguous.

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 does so thoroughly. It discloses preview-mode default, commit behavior, update semantics for omitted fields, XML validation, inherited-field checks, metadata error blocking, and size limits. This is unusually transparent for a mutation tool.

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

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

The description is long but every sentence carries operational value. It front-loads the core purpose and default behavior, then uses a structured Args list to map details to parameters. The format is scannable and free of 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?

Given a five-parameter write tool with no annotations, the description is complete: it covers action constraints, required fields, data format, size limits, preview flow, XML behavior, and error conditions. An output schema exists, so not describing the full return shape is acceptable. Nothing essential for invoking the tool correctly is missing.

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

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

The description compensates fully for the 0% schema description coverage by documenting every parameter: action enum values, table and sys_id requirements, data format and maximum size, and preview semantics. It adds meaning well beyond the bare schema titles and defaults, including required conditions per action.

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

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

The description explicitly states the tool creates, updates, or deletes a record, using specific verbs and a clear resource. It differentiates from siblings like record_apply (which commits previews), record_read (which reads), and attachment_write (which writes attachments). The purpose is immediately understandable and distinct.

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

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

The description clearly defines the actions this tool supports and explains when the preview mode requires calling record_apply to commit. It does not explicitly contrast with record_read or other sibling write tools, but the action-specific guidance and preview/commit flow provide solid contextual direction. It lacks an explicit 'when not to use' statement, so it falls just short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It explains the conditional behavior (returns mapping if label empty) but does not disclose error handling, authentication requirements, or rate limits. The read-only nature is implied but not explicitly stated.

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

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

The description is concise with only three sentences, front-loading the purpose and listing parameters efficiently. No unnecessary words.

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

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

Given the tool's simplicity and the existence of an output schema, the description covers key behaviors. It could mention the output format more explicitly, but overall it is sufficiently complete for an agent to use correctly.

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

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

Despite schema description coverage being 0%, the description explicitly explains each parameter: 'ServiceNow table name', 'Field name on that table', and the special behavior of the label parameter when empty. This adds significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: resolving a choice label to its underlying value via ChoiceRegistry. It also distinguishes from siblings by specifying a unique function not shared by other tools in the list.

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 resolving choice labels and optionally getting the full mapping when label is empty. However, it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives among siblings.

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

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

The description lacks disclosure of behavioral traits such as idempotency, side effects (e.g., order_now is likely destructive), or required permissions. No annotations exist to compensate. While actions like 'catalogs_list' are read-only, actions like 'cart_checkout' imply write operations, but this is not clarified.

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

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

The description is well-structured with a clear opening line and a bullet list of parameters. It is reasonably concise given the complexity of 11 parameters and multiple actions. Minor redundancy exists (e.g., repeating action names in parameter explanations), but overall it is efficient.

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

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

For a tool with 11 parameters and many actions, the description covers most critical usage aspects: parameter-action mappings and defaults. Since an output schema exists, the lack of return value descriptions is acceptable. However, ordering constraints or pagination details could be more explicit.

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

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

The input schema has no parameter descriptions (0% coverage), but the description adds meaningful context by explicitly listing which parameters apply to which actions (e.g., sys_id for catalog_get). This significantly compensates for the schema gap, though a few parameters like 'variables' could have more detail on format.

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

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

The description clearly states that this tool handles Service Catalog operations by dispatching on an 'action' parameter. It enumerates specific actions like catalogs_list and order_now, making the resource explicit. However, it does not differentiate from sibling tools like 'query' or 'record_read', which might also handle catalog-related 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?

No guidance is provided on when to use this tool versus alternatives. The description simply lists actions without indicating preferred use cases or dependencies. Given the sibling tools (e.g., 'query', 'record_read'), explicit guidance on when to use this dispatcher would improve clarity.

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