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

Annotations already declare the read-only/idempotent/non-destructive profile, but the description goes well beyond them: profiles have no UUID so the name is the identifier everywhere, secrets are masked by the API, wildcards are accepted by the platform but not by this tool, and it enumerates the exact error strings returned on failure.

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

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

Front-loaded with purpose, then Read-only note, then Args and Returns sections. The enumeration of four distinct error strings is slightly verbose but each is actionable for an agent and the rest is 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?

Covers identifier model, masking behavior, wildcard caveat, and failure modes. With an output schema present, the description does not need to explain return values, and its added behavioral context leaves an agent fully equipped to call 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 coverage is 100% and the schema already documents the single profile parameter, so the baseline is 3. The description adds real value beyond it: matching is case-insensitive, surrounding whitespace is stripped, and a '*' wildcard is accepted by the platform but rejected here – detail the schema does not convey.

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 (get) and resource (credential profile) with scope 'one ... by name'. It also distinguishes itself from the sibling cnc_list_credential_profiles, so an agent can tell the two apart without opening a schema.

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 routes discovery to 'Find names with cnc_list_credential_profiles' and states the condition that selects this tool: a single exact match is required. Nothing about when to use it over the list sibling is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds real behavioral context: the read/write type asymmetry on node_ip.inet_af that makes round-tripping into a write unsafe, plus precise error-string semantics. That is value well beyond the annotation set.

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

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

Front-loads the purpose, then constraints, then error semantics — a sensible order. Slightly long: enumerating every returned field is redundant given an output schema exists, so a few lines do not fully earn their 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?

Covers selection rules, read-only nature, notable data pitfalls, and both error shapes. With an output schema present it does not need to describe the return payload, so nothing an agent needs to call this 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?

Schema coverage is 100%, so uuid/host_name are already documented. The description still adds meaning: exactly one selector must be supplied, and the two selectors behave differently on ambiguity since only uuid guarantees a unique match. Minor tension: it mentions a 'wildcard host_name' while the schema declares exact match.

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 ('Get'), resource ('full inventory record of one device'), and both accepted selectors (uuid or host name). The singular 'one device' cleanly separates it from the sibling cnc_list_devices.

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

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

Explicitly instructs 'Pass exactly one selector' and explains the two failure modes and their remedy (not found vs. ambiguous wildcard -> use the uuid). It does not name cnc_list_devices as the alternative for enumeration, but the singular scope makes the choice inferable.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the description's 'Read-only' line is redundant. However, it adds genuine behavioral context beyond structured fields: the exact status categories counted and the failure surface ('On failure: "Error: ..."'). This is solid added value, short of exceptional.

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

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

Front-loaded with the purpose, then usage, then return shape. Every block is relevant, though the 'Read-only' line repeats annotations and the explicit Returns block is somewhat redundant given an output schema exists. Minor padding, no real waste.

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

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

For a zero-parameter aggregate tool whose safety profile is covered by annotations and whose return shape is backed by an output schema, the description is complete: purpose, use case, alternative, and count semantics are all present.

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 takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate on inputs, and it correctly spends no words on 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?

States a specific verb (count) and resource (devices by collection status) with an explicit scope (across the whole inventory). It further disambiguates from the sibling cnc_list_devices by contrasting the aggregate widget against drilling into individual devices.

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

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

Explicitly says when to use it ('quick health check before drilling into individual devices') and names the alternative tool (cnc_list_devices) for a different granularity. The routing condition is clear enough that an agent need not infer it.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description still adds real context: the scan window limitation (newest few hundred jobs, newest first, so very old jobs may not be found), the success-with-warning semantics of JOB_COMPLETED_WITH_WARNING, and the exact error-string behavior. These are behavioral traits not encoded in annotations.

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

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

Front-loaded with the one-line purpose, then usage, then a structured returns block. Every sentence earns its place: the scan-window caveat and warning-state note are non-obvious and actionable, and nothing is redundant.

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

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

For a single-param read tool with an output schema and full annotations, this covers purpose, alternatives, lookup limitations, and return shape including edge cases (warning state, not-found error). Nothing an agent needs to call it 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?

Schema description coverage is 100% and the single job_id parameter is already documented with its source and an example, so the schema carries this burden. The description adds little parameter-level detail beyond confirming the id is the lookup key. Baseline 3 is appropriate when the schema does the heavy lifting.

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 and resource ('Get one inventory job by id') and enumerates exactly what is returned: state, type, timestamps, impacted objects, and error text. It explicitly distinguishes itself from siblings cnc_wait_for_inventory_job and cnc_list_inventory_jobs by name, so an agent can route without opening the schema.

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 explicit when-to-use ('check the outcome of a device/credential/provider write') and a when-to-prefer-alternative rule ('For a job that may still be running prefer cnc_wait_for_inventory_job, which polls until it finishes'). It also names the fallback for old jobs (cnc_list_inventory_jobs can page to it). This is the full when/when-not/alternative set.

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

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

Annotations already cover read-only/idempotent safety, so the bar is lower, yet the description adds non-obvious behavior: the uuid lookup is a client-side scan because uuid is 'not a verified filter field', and read objects must not be round-tripped into write bodies (inet_af differs). It also enumerates error conditions. This is real operational context beyond the annotations.

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

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

Front-loads the one-line purpose, then uses a Returns block and parenthetical asides to carry the quirks. Structure is good, but the Returns section is somewhat verbose given an output schema exists, and some phrasing ('as Crosswork returns it') repeats what structured output already implies.

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

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

With annotations (safety), a full input schema, and an output schema already present, the description fills the remaining gaps: selector exclusivity, uuid scan behavior, error cases, and the read/write field-format mismatch. Nothing an agent needs to call this 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?

Schema coverage is 100%, so the baseline is 3; the description still adds value by reinforcing the mutual-exclusivity of uuid/name and by explaining that uuid matching happens client-side because it is not a verified filter field, which affects how the agent should source the value. It stops short of adding format details 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?

States a specific verb (get) and resource (one provider) with scope qualifiers (by UUID or exact name), and distinguishes itself from the sibling cnc_list_providers by returning 'the full record of one provider'. An agent can tell it apart from list/get_collection tools without opening a schema.

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 an explicit rule ('Exactly one of uuid/name must be given'), names the scenarios where it applies (before cnc_update_provider or cnc_delete_provider), and routes to the alternative (verify with cnc_list_providers) when no match occurs. Both selection constraints and the fallback path are spelled out.

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?

Far beyond the annotations: it discloses that Crosswork returns the whole graph with no server-side paging, so every call re-downloads and pages client-side, that link endpoints are pre-resolved so a links page is self-contained, that icon/checksum and edge-decoration attributes are dropped, and that an HTTP 500 is deterministic and must not be retried.

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

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

Front-loaded with the core fact and cleanly sectioned into Args/Returns/error handling. The verbose JSON return-shape listing is somewhat redundant against the existing output schema, which costs it a point, but little of the prose is 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?

For a 6-parameter read tool with annotations and an output schema, the description still supplies the non-obvious operational context: client-side paging rationale, endpoint resolution, dropped attributes, page-size limits, and the deterministic-500 error contract.

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 already 100%, so the baseline is 3, but the description adds the cross-parameter model — that page/page_size window links while node_page/node_page_size window nodes, and that map_type accepts only 'logical'. This explains the interaction between parameters rather than just restating them.

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

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

The opening line gives a precise verb and resource plus the exact shape of the payload ('one page of nodes plus one page of links'). It explicitly distinguishes itself from the sibling tools cnc_list_topology_nodes / cnc_list_topology_links by naming them and the attribute category each covers.

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 states the use case with a concrete example ('what is PE1 connected to?') and gives an explicit when-not with the alternative tools for tabular attributes. It also adds a sizing caveat ('keep page sizes modest') that shapes invocation.

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

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

Annotations already cover read-only/idempotent, but the description adds substantial context beyond them: it discloses that three topology-service calls are combined, explains empty-body semantics (null counts, empty breakdowns), the failure format, and a critical non-retry rule for HTTP 500 body rejections, distinguishing it from the inventory's NATS failure signal.

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

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

Front-loaded with the one-line purpose, then usage guidance, then a structured Returns block. The return-shape transcription borders on redundant given an output schema exists, but the semantic annotations attached to it (unmapped_nodes meaning, empty-body behavior) justify most of the length.

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

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

Covers purpose, ordering guidance, alternative tools, return semantics, empty-topology interpretation, and error handling with a non-retry directive. Nothing an agent needs to call this zero-parameter 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 tool takes zero parameters, so there is nothing to disambiguate; baseline for 0 params is 4. The description correctly implies no filtering input is required.

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 ('Summarize the CNC topology') plus the exact scope (node/link totals and state breakdowns), and explicitly names the sibling tools used for drilling in (cnc_get_topology, cnc_list_topology_nodes, cnc_list_topology_links). An agent can distinguish this from the drill-in siblings without reading any schema.

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

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

Explicit ordering guidance: 'Use it first to learn whether the topology is populated at all,' with a concrete diagnostic rule (empty topology + populated inventory ⇒ no reachable SR-PCE provider), then routes to the appropriate drill-in alternatives. Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds genuine behavioral detail beyond them: paging is done via a SQL-like criteria string, no total is reported, and 'has_more' just means the page came back full. These quirks materially affect correct invocation.

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 purpose is front-loaded and easy to scan, but the description is bloated by an Args block that duplicates the schema and a very long Returns block that restates a full JSON shape despite an output schema existing. Those sections do not fully earn their 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?

For a list tool with annotations and an output schema present, the description is complete enough: it covers purpose, paging, filtering limits, and error format. The only excess is redundant return-value detail, not a gap in coverage.

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 four parameters. The Args block restates open_only, limit, and page without adding syntax or edge-case meaning beyond what the schema provides. 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?

States a specific verb and resource ('List Crosswork platform alarms') and even enumerates what the alarms cover (device reachability, collection, application health) plus ordering ('newest first'). It also implicitly distinguishes itself from siblings (devices, providers) by positioning itself as the diagnostic entry point.

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 clear when-to-use guidance: 'find out why something is unhealthy before digging into devices or providers,' which routes the agent to deeper sibling tools. It also notes that 'no other filtering is exposed' beyond the criteria string, an implicit constraint. No explicit when-not-to-use, so not a full 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so 'Read-only' mostly restates structured data. The one genuinely additive behavioral detail is the failure mode ('Error: <actionable message>'), but nothing is said about latency, pagination, or freshness of the installed-application data.

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 purpose and usage sentences are front-loaded and efficient, but the large 'Returns' block unpacks a nested JSON payload field-by-field, which is substantial duplication given an output schema exists. Roughly half the text is redundant structure rather than guidance.

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 is inherently simple (one optional param, read-only), and the description covers purpose, usage context, and failure behavior. Since an output schema exists, the detailed return enumeration is unnecessary rather than missing, so completeness is high.

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

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

Schema description coverage is 100% with a single optional response_format parameter whose enum and per-value meaning are documented in the schema. The description never mentions response_format, so it adds no meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('List the applications installed on the Crosswork platform') and concretely grounds it with examples of the applications returned. It is clearly distinguishable from the device, credential, provider, and topology siblings, which all operate on different resources.

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

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

Gives explicit situational guidance: use it to check what is installed and at which version before assuming a feature (topology, SR-TE, VPN services) is available. It doesn't name a competing sibling or a when-not-to-use case, but for a simple unfiltered list tool the usage context is clear.

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

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

Beyond the annotations (readOnly/idempotent/openWorld), the description discloses that secrets are masked as '******' while usernames are clear, and maps failure modes (500 NATS request failed, 403 token rejected or missing privilege). That is auth/behavioral context the annotations cannot convey.

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

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

Front-loaded with purpose and routing, then cleanly sectioned into Args and Returns. The Returns block is verbose and largely duplicates the existing output schema, which is the main place text is not fully earning 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?

For a 4-param read-only list tool, the definition covers purpose, alternatives, filters, paging, output shape, and error semantics. An agent has everything needed to call it correctly and interpret results.

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 the baseline is 3, but the description adds semantics the schema lacks: surrounding whitespace is stripped, a blank filter means no filter, and paging is explicitly 0-based with the response_format default restated. It goes modestly beyond the schema rather than merely echoing it.

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

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

First sentence states a specific verb (List) and resource (credential profiles) plus scope modifiers (name filter, paging). It explicitly contrasts itself with the sibling cnc_get_credential_profile, so the agent can route without inspecting either schema.

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 concrete when-to-use reasons ('find the profile name to reference when adding devices or providers', 'check which protocols a profile covers') and names the alternative for the single-record case. Nothing is left to inference.

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

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

Beyond the readOnly/idempotent annotations, it discloses that filters AND together, that unmanaged devices are included unlike the UI, and documents failure modes with actionable error semantics ('unknown enum value -> accepted values listed', 500 NATS failure meaning). This is unusually rich behavioral context.

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

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

Front-loaded with purpose, usage, then Args/Returns. Well-organized, though the Returns block is long and partially redundant with the existing output schema.

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-param, filter-heavy read tool with an output schema, this covers discovery intent, filter combination, visibility caveats, paging, and error behavior comprehensively. Nothing an agent needs to call it 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?

Schema coverage is 100%, so the parameter descriptions already carry most semantics. The description adds the cross-parameter rule that filters are AND-ed together and repeats the case-insensitive/'*' wildcard and 0-based paging contract, which is useful but largely mirrored 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?

States the specific verb+resource ('List network devices (inventory nodes)') plus scope ('optional filters and paging'). It even clarifies that these devices are inventory nodes, distinguishing it from the topology-oriented 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?

Explicitly routes the agent: use this to discover uuids/host names before calling cnc_get_device, cnc_update_device or cnc_delete_device. It also warns that unmanaged devices are hidden in the CNC UI default table but returned here, preventing a wrong inference about coverage.

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

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

Annotations already declare readOnlyHint/idempotentHint and no destruction, but the description adds real behavioral context: pagination grammar, the fact that 'total' is null when the platform reports no result_count, and that 'has_more' then means the page came back full. It also interprets job states (e.g. COMPLETED_WITH_WARNING is a success with an advisory in 'error') and failure format. The bulk of the return-value detail, however, overlaps the output 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?

Front-loaded with purpose, scope, and routing in the first two paragraphs, and the hedging on the pagination grammar ('assumed for this endpoint') is honest. It is somewhat over-long, however: the full Returns JSON shape duplicates information already present in the output schema.

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 paged, read-only list endpoint, the definition covers purpose, routing alternatives, pagination caveats, item fields, state interpretation, and failure output. An output schema exists, so the return-shape narration is bonus rather than a gap, and nothing an agent needs to call it 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?

Schema description coverage is 100%, so the schema already documents page, page_size and response_format. The description's Args line ('page_size / page: page size and 0-based page number') merely restates the schema, adding no new syntax or constraints — baseline 3.

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 and resource plus its exact scope: 'the audit trail of every device, credential, provider and tag write on Crosswork (each write returns one job).' This clearly separates it from the singular cnc_get_inventory_job and the blocking cnc_wait_for_inventory_job.

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 names two use cases ('review recent changes' and 'find the job_id of a write whose result was lost') and routes the agent to the correct follow-up tools (cnc_get_inventory_job, cnc_wait_for_inventory_job) with the condition for each.

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

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

Annotations already cover the safety profile (readOnly/idempotent/non-destructive/openWorld), and 'Read-only' restates them. The description does add genuinely non-annotated behavior: response_format output contents, 0-based paging with has_more/next_page, the null/absent semantics of total vs collection_total, and concrete error semantics (unknown family returns accepted values; 500 NATS request failed means malformed request, not an outage).

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

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

Front-loaded and organized with clear sections, but verbose: the Args block largely restates the 100%-covered schema and the Returns block reproduces the full JSON shape even though an output schema exists. The one valuable non-redundant detail is the total-vs-collection_total distinction on zero matches.

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-only list tool it covers everything an agent needs: what it returns, how to page, how filters combine, the sibling to use for detail, and how to interpret failure messages. Missing values for providers/reachability are explained via the field semantics.

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 the baseline is 3; the description still adds cross-parameter meaning not in the schema, notably that filters AND together, that only name and family are honored on this endpoint, the accepted family values, and what each response_format yields. The name wildcard rule is repeated from the schema rather than extended.

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?

Names a specific verb and resource ('List the providers configured in Crosswork'), enumerates the concrete provider types (SR-PCE, NSO, WAE), and explains what a provider is and which one feeds the topology. It is trivially distinguishable from cnc_get_provider, which it names.

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

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

Explicitly states when to use it ('discover provider UUIDs and check their reachability before touching devices, topology, or services') and names the alternative for the other case ('use cnc_get_provider for the full record'). It also states the filter composition rule (filters AND together) and which filters this endpoint supports.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds non-obvious implementation detail: the tool sends an empty body, filters and pages client-side, and warns the server-side behavior is unverified. It also defines 'total' vs 'collection_total' and the truncation signal, which no annotation or schema conveys.

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 two opening sentences are front-loaded and efficient, but the implementation caveats ('Whether tags/query honours a filter body or pages server-side is not verified...') and the full inline return-shape block are verbose and partly duplicate the output schema.

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

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

Covers purpose, trigger, parameter behavior, the truncation edge case, and the total/collection_total distinction despite an output schema existing. The main gap is a slightly bloated return-value restatement, but overall the agent has what it needs to call and interpret the tool.

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

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

Schema coverage is 100% and each param is described there, so baseline is 3. The description adds value by clarifying that name/category are applied client-side after the fetch and by explaining paging behavior, going beyond the schema's field-level 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 first sentence states a specific verb and resource ('List the tags defined on Crosswork') plus the scope (system tags like 'mdt' plus user-defined). The following sentence gives the downstream use case, and no sibling tool overlaps this purpose.

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

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

Explicitly states when to use it: 'Use it to learn the exact tag names before filtering devices by tag or attaching tags to devices.' This gives an unambiguous trigger, which is rare in the sibling set.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so 'Read-only' is redundant, but the description goes well beyond them: paging as a row window, past-the-end pages returning totalCount with no rows (not an error), no filtering available, and the deterministic HTTP 500 meaning the request body was rejected and must not be retried. That is substantive behavioral context, though the data-source caveat is the only precondition and auth/rate limits are untouched.

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 purpose is front-loaded and the Args section is tight, but the Returns block reproduces a full JSON item shape even though an output schema already exists, and the error-handling aside is a long parenthetical. Sizeable portions of the text do not earn their place against existing structured fields.

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-only paged list tool, the description covers paging edge cases, the no-filtering constraint, data-source prerequisites, and error semantics, and an output schema already carries the return shape. An agent has what it needs to call it correctly without guessing.

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 page, page_size and response_format are already documented. The description adds only the startRow/endRow paging formula, which is a modest gain over the schema's 'rows per page' wording; the 1-500 bound and markdown/json values merely restate 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?

States a specific verb+resource ('List the links (edges) on the topology map') and immediately scopes what each element is. Combined with its sibling names (list_topology_nodes, get_topology, get_topology_summary) an agent can tell it returns the edges rather than nodes or a summary.

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 description notes that link population depends on data sources (L2 via LLDP, L3 requires an SR-PCE provider/BGP-LS). But it never states when to pick this over cnc_list_topology_nodes or cnc_get_topology, nor any explicit 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?

Despite annotations already declaring read-only/idempotent behavior, the description adds substantial behavioral context: paging is a row window, past-the-end returns totalCount with no rows rather than an error, unknown sort columns are silently accepted by the platform but validated here, and an HTTP 500 means a deterministic rejection that should not be retried.

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

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

The description is structured with Args and Returns sections and front-loads the primary purpose and sibling routing. It is detailed but most sentences carry operational value; some return-format detail is redundant given the output schema.

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-only, paged, filterless list tool with annotations and an output schema, the description covers the key edge cases: paging behavior, lack of server-side filtering, sort validation, and non-retryable HTTP 500 failures. Nothing material is missing 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 100%, so the baseline would be 3. The description adds paging semantics beyond the schema, including the formulas startRow = page * page_size and endRow = startRow + page_size, and notes that sort_by is locally validated against unknown columns.

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 and resource: 'List the nodes on the topology map as a sorted, paged table.' It also distinguishes the tool from its sibling cnc_get_topology, which is for adjacency rather than per-node attributes.

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

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

Explicitly says to use this for per-node attributes and directs adjacency queries to cnc_get_topology. It also states there is no filtering on this endpoint and recommends client-side filtering or inventory tools as alternatives.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description reinforces that while adding non-obvious traits: the Password field is never returned, the platform's PascalCase dict is flattened to a list, and a 403 indicates the configured account lacks user-administration privilege. These are genuinely useful behaviors not present in structured 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?

Front-loads purpose, then usage, then returns and failure modes in labeled blocks. The Returns section is fairly long, but every element (count/items field names, error prefix) carries information an agent would otherwise have to guess.

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?

Even though an output schema exists, the description fully covers return shape, field names, failure string format, and the 403 case, so an agent can call and interpret results without further 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?

Only one optional parameter (response_format) and the schema already documents it at 100% coverage. The description nevertheless earns credit by tying each format to a concrete return shape in the Returns block, going beyond the schema's terse enum 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?

States a specific verb (List) plus resource (Crosswork user accounts) and enumerates the fields returned (role, status, device access groups). No sibling tool competes for this resource, so it is unambiguously distinguishable from the device/topology/provider listings.

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 gives two use cases: confirming an account exists (with a useful rationale about identical 'Invalid credentials' responses) and inspecting role/device access groups. It does not name alternatives or exclusions, but none exist among the siblings, so context is clear without them.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds critical behavior beyond them: a timeout is explicitly NOT an error and the caller should re-invoke, the typical UNKNOWN/CHECKING -> REACHABLE timeline, and the shape of both success and timeout responses. This is exactly the kind of convergence-wait context an agent needs.

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

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

Front-loads the core action, then usage, then return semantics in a logical order. Slightly long, and the Returns block partially restates the output schema, but every line (notably timeout-is-not-an-error) carries information. Minor redundancy is the only deduction.

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 an output schema and full annotation coverage present, the description still supplies the missing semantic layer: mutual-exclusive selector params, timeout semantics, and expected device-state transitions. Nothing an agent needs to invoke and interpret the result is absent.

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, but the description adds a real constraint the schema cannot express: pass exactly one of uuid / host_name. It also ties uuid back to cnc_create_device's impacted_objects. The timeout/interval parameters are left to the schema, which is adequate.

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 action and target: 'Poll a device until its reachability_state is CONN_STATE_REACHABLE.' It names the exact terminal state and, via the usage line, distinguishes itself from plain polling with cnc_get_device. An agent can select it without opening any schema.

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 explicit when-to-use ('right after cnc_create_device', 'after fixing credentials / admin state') and names the alternative it replaces ('instead of polling cnc_get_device in a loop'). It also states the mutual-exclusion rule ('Pass exactly one of uuid / host_name').

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, but the description adds substantial behavioral detail: terminal states, warning semantics, timeout-as-non-error handling, and error return shapes. Nothing contradicts the annotations.

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

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

The first sentence is front-loaded and the usage guidance is clear. The returns block is lengthy and partly overlaps the output schema, but it earns its place by explaining timeout and warning behavior.

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 asynchronous polling tool with annotations, a full input schema, and an output schema, the description is complete enough to call correctly. It covers usage context, terminal states, timeout behavior, and error semantics.

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 job_id, timeout_seconds, and interval_seconds are already documented in the schema. The description alludes to timeout behavior but does not add syntax, defaults, or constraints 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?

States a specific verb and resource: poll an inventory job until terminal state or timeout. It distinguishes itself from the sibling cnc_get_inventory_job by explicitly saying to use this instead of calling that tool in a loop.

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 explicit when-to-use guidance: right after a write returns JOB_RUNNING, rather than polling cnc_get_inventory_job manually. It also clarifies that timeout is not an error and that the caller should call again to keep waiting.

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