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

With readOnlyHint already covering safety, the description goes far beyond annotations: it explains null-vs-error semantics, 'complete: false' meaning partial reads, 'notFound' semantics, 'tagRelations' missing-target interpretation, FEX/vPC path matching, and what the read deliberately does not evaluate (notChecked). This is unusually rich behavioral disclosure for a read tool.

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

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

Front-loaded with [READ] and the one-line purpose, then organized into labelled bullet blocks for result interpretation. It is long, but nearly every bullet addresses a distinct misreading risk; the only cost is bulk, not 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?

There is no output schema, yet the description enumerates the return dict shape (query, endpoints[...], findings, errors, returned/limit/truncated, notFound) and explains the meaning of the ambiguous fields. Given the complexity of the traversal, this is complete enough for an agent to call and interpret 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%, so the description carries the full burden — and it does: all five params are documented, including case-insensitivity and MAC example, mac-XOR-ip exclusivity, limit default 5/max 20 plus the returned/limit/truncated result fields, fault_limit default 20, and the target value constraint 'platform: aci'.

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?

[READ] plus a specific verb ('Reconstruct') and resource ('ACI endpoint's static fabric path'), scoped to MAC or IP input. The enumerated chain (endpoint → attachment → EPG → BD → VRF → contracts → filters) makes the operation concrete and distinguishable from siblings like aci_faults_list or aci_epg_segment.

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 calling conditions ('Pass mac OR ip') and strong scope exclusions, most importantly that it is NOT a reachability test and that fabric path resolution is not traffic flow. No sibling tool is named as an alternative (e.g. aci_faults_list for raw faults), leaving the routing 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?

Annotations only declare readOnlyHint=true, but the description adds substantial behavioral context: it follows APIC-resolved relations (including cross-tenant 'common' links), expands contracts to filter entries, explains that non-'formed' relations become findings, that failed reads are null with an 'errors' entry, and that an unenforced VRF does not restrict traffic. This is richer than the annotation alone.

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 [READ] tag and one-line purpose before the traversal, edge-case, and args sections. It is on the long side but each block (traversal semantics, error handling, notChecked scope) earns its place without redundancy.

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

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

With no output schema, the description carries the return-shape burden and enumerates the full dict (epg, bd, vrf, contracts with truncation flags, segmentResolved, notChecked, findings, errors). Combined with the scope and error-handling details, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 0%, so the description must compensate, and it documents all four args including the critical constraint that target 'must be platform: aci'. Word-level semantics for tenant/app/epg are adequate though minimal beyond the example.

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 ('An ACI EPG's segment: bridge domain, VRF and contracts, by name') and describes the traversal it performs. It also implicitly distinguishes itself from sibling aci_endpoint_trace by noting 'Use it when you know the EPG but not an endpoint in it,' so an agent can tell the two apart.

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

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

Gives a clear when-to-use condition ('when you know the EPG but not an endpoint in it') that effectively points away from the endpoint-trace sibling. There is no explicit when-not or named alternative, but the routing intent is 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 only readOnlyHint=true in annotations, the description adds substantial behavioral context: how 'active' is derived, that delegated records mirror faults raised elsewhere, that cleared faults retain stale descriptions, how sorting works within a severity, and that truncation makes 'latest' claims unsafe. These are non-obvious semantics an agent could not infer from the annotation alone.

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 in the first line and the dense prose is mostly load-bearing semantics rather than filler. It is long, and the inline Returns block partially overlaps what an output schema would normally carry, but since no output schema exists that content is justified; only minor tightening is possible.

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

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

Given no output schema and 0% param coverage, the description supplies the return shape (faults, bySeverity.serverReported, returned/limit/truncated, delegatedRecords), per-parameter meaning, and interpretation caveats. Nothing needed to call or correctly interpret the tool appears to be 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 0%, so the description carries the full burden and does so well: it enumerates the severity values (critical/major/minor/warning/info/cleared) that the schema's free-form string lacks, explains include_cleared's interaction with severity being omitted, gives limit's default and max, and specifies target must be 'platform: aci'.

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 ('[READ] ACI fabric faults') plus the ordering ('worst severity first'), which immediately distinguishes it from the other ACI siblings (aci_epg_segment, aci_endpoint_trace) that deal with topology rather than faults. An agent knows exactly what domain this operates on before 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?

Provides strong operational guidance: don't double-count delegated records, re-run with a higher limit when 'truncated' is true, and don't treat cleared descriptions as current state. It stops short of naming sibling alternatives (e.g. vs network_alerts) or explicit when-not-to-use conditions, so it lands at clear-context rather than full routing guidance.

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

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

With annotations only flagging destructive/non-idempotent, the description goes far beyond: it discloses the refusal trigger and why (undo would report success restoring nothing), the precise undo semantics per prior state, and the exact partial-restore scope (binding state only, NOT firewall rules / group policies / static routes). This is exactly the destructive-behavior detail 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-loaded with the risk tags, then refusal, undo, and preview semantics in priority order before the args list. Sentences are dense with multi-clause undo logic but every clause carries decision-relevant information; nothing is filler, though the density costs some readability.

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 high-risk, no-output-schema mutation with 5 params, the description covers refusal, preview safety, and undo/partial-restore consequences thoroughly. It could still note what a successful response returns or any template-existence precondition, but the behavioral picture is essentially 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 description must carry all parameter meaning, and it documents all five with non-obvious detail for auto_bind (Meraki autoBind flag), dry_run, and target (omit for default). The two required IDs get only restated descriptions, but those are self-evident.

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 (bind a network to a config template) and immediately tags it [WRITE][risk=high], which is unambiguous. It is clearly distinguishable from the sibling unbind_network_from_template, and the refusal condition further scopes exactly what class of bind the tool will accept.

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 strong contextual guidance: it names the exact condition under which the call is refused (unbound network with local VLANs) and steers the agent to dry_run=True for previewing. It does not, however, explicitly route to related siblings (unbind_network_from_template, config_template_drift) as alternatives, leaving that to the agent.

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

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

Annotations declare write/not-idempotent/destructive, and the description adds real context beyond them: it is a POST to the controller, records no undo, and makes no configuration change. The tiering paragraph explains why it is tagged a write, though it is somewhat framework-meta rather than invocation-relevant.

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 verb and intent, but the middle paragraph defends the risk tiering at length, which is mostly framework meta-commentary that doesn't help an agent invoke the tool. Some of that prose does not earn 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 3-param write tool with no output schema, the description covers all parameters, the absence of undo, and the non-config-changing nature. It is adequately complete, missing only details like the response shape or permission requirements.

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 carry parameter meaning, and it does: it documents serial, duration (range 5..120, default 20), and target (omit for default). This compensates well for the schema gap, though it adds no serial format details.

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

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

States a specific verb and resource ('Blink a device's locator LEDs') plus the intent ('to find it physically'). This makes it clearly distinguishable from sibling write tools like reboot_device and update_device.

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 conveys the purpose context (physical location aid) and notes no config change, which implies when it is appropriate. However, it names no alternatives or explicit when-not conditions, so routing guidance is implied rather than stated.

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=false, destructiveHint=true, idempotentHint=false. The description adds value beyond those: the [WRITE][risk=high] tag, the fact that claimed serials are recorded so the harness can offer an undo, and the dry_run preview path. Doesn't cover failure modes or auth requirements, so not a 5.

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 severity tag and one-line purpose, then an Args block. Every sentence earns its place, though the Args list partly restates parameter names already visible in the 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 high-risk mutation with no output schema, the description covers the write semantics, undo behavior, dry-run safety, and all parameters. Auth/permission prerequisites and the undo workflow specifics are the only meaningful gaps.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it documents all four: network_id, serials, dry_run (preview only), and target. It compensates well for the coverage gap, though it adds no format/constraint detail (e.g. serial list limits).

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 (claim devices into a network) and explicitly names the inverse operation, letting an agent distinguish it from the sibling remove_device_from_network without opening 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 clear context: use it to claim, with the inverse operation called out for the reverse direction, and notes dry_run previews and that target can be omitted for the default. It stops short of explicit when-not-to-use conditions, so a 4.

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

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

Annotations already declare readOnlyHint=true, and the '[READ]' tag is consistent with that. The description adds the enumerated stat categories, but discloses nothing about error behavior, time windows, or response shape beyond what the annotations and name imply.

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

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

Front-loads the read purpose in one bracketed sentence and then a compact Args block. No redundant prose; the only minor cost is that the enumerated stat abbreviations are unexplained.

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 output schema and 3 params at 0% schema coverage, the description covers the inputs adequately and hints at return content via the stat categories. It stops short of describing the response structure or time range, leaving a modest gap for an agent deciding whether the result answers its question.

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

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

Schema coverage is 0%, so the description carries the full burden and largely meets it: network_id ('Meraki network id'), client_id ('Client id/MAC (from client_list)'), and target ('Target name from config; omit for the default'). The target semantics are genuinely clarifying (a config profile, omit for default), though acceptable value formats for network_id are not detailed.

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 resource ('A client's connection-quality stats') and enumerates the stat categories captured (assoc/auth/dhcp/dns/success), which is more concrete than a generic 'get client info'. It is distinguishable from client_usage/client_get, though it never names the sibling it differs from.

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 tells the agent where client_id comes from ('from client_list'), which is useful routing, but gives no explicit when-to-use/when-not guidance versus client_usage, client_get, or network health tools. Usage is implied by the resource rather than stated.

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?

readOnlyHint=true already establishes this as a safe read, so the bar is lower; the [READ] tag merely restates it. The description adds the set of fields returned and the target-omission default, but says nothing about rate limits or pagination behavior.

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

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

The [READ] marker and resource summary are front-loaded, followed by a compact args block. Every line earns its place, with no filler.

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

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

No output schema exists, but the description lists the key return fields, and all parameters are covered. The only soft spot is the vague 'Target name from config' phrasing, which leaves an agent guessing what a target represents.

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 carry the load, and it documents all three parameters: network_id, client_id (with a hint it comes from client_list and accepts a MAC), and target (omit for the default). This meaningfully compensates for the empty schema.

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

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

States a specific verb (get) and resource (one client's detail), and enumerates the returned fields (description, MAC, IP, VLAN, manufacturer). It implies differentiation from client_list by naming it as the source of client_id, though it never explicitly contrasts the two tools.

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

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

Usage is only implied: client_id comes 'from client_list', suggesting this is the single-record counterpart to that list tool. There is no explicit when-to-use vs client_usage or client_connectivity, nor any exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, and the '[READ]' prefix merely restates that. The description does add the timespan bounds (7200..2592000, default 86400), which the schema lacks, but says nothing about pagination, result caps, or the shape of a returned client record. Adequate against a low annotation bar, not rich.

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

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

Front-loaded one-line purpose followed by a compact Args list; no filler sentences. The '[READ]' tag is slightly redundant with the annotation but is cheap. Structure is easy to scan 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?

For a read-only list tool with no output schema, the description covers the arguments and the general nature of the result ('clients seen on a network'). It stops short of describing return fields, ordering, or pagination behavior, but nothing required to invoke 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?

Schema description coverage is 0%, so the description carries the full burden and largely meets it: it gives network_id provenance (from network_list), the timespan range and default, and the meaning of target. The only weak spot is 'Target name from config', which is vague about what valid targets exist. Given a 0% coverage schema, this is strong compensation.

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 with scope: lists clients 'seen on a network within a look-back window'. That distinguishes it from siblings like client_get, client_usage, and client_connectivity. However, it never names an alternative tool, so the differentiation is inferred from the name rather than stated.

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 description (retrieve clients on a given network) and it helpfully notes that network_id comes from network_list. There is no explicit when-to-use vs. when-not guidance and no routing to client_get or client_usage for per-client detail, so the agent must infer the boundary.

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 provide readOnlyHint=true, confirming a safe read operation. The description adds the aggregation detail (rolled up to total sent/received KB), but does not disclose return format, historical time span coverage, or rate limits. With annotations covering safety, this extra detail is moderate value.

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 [READ] and purpose. The Args block is standard and each line is short. One sentence intros plus three parameter lines, no fluff, though the target line is a bit cryptic and could be trimmed or improved.

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 tool with no output schema, the description should ideally explain return values or time range. It covers what the tool does and identifies parameters, but misses context about aggregation period, data freshness, and required permissions. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description carries full parameter burden. It names network_id as 'Meraki network id' and client_id as 'Client id/MAC (from client_list)', adding some meaning beyond the schema's bare types. However, the target parameter explanation ('Target name from config; omit for the default') is vague and doesn't clarify what config refers to or what the default is. Two of three parameters get only basic identification, leaving gaps.

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

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

States a specific verb (rolled up) and resource (client's usage history into total sent/received KB). The scope is clear enough to distinguish from sibling client_list and client_connectivity, though it doesn't explicitly name them as alternatives.

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

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

No explicit when-to-use or when-not-to-use guidance. The description alludes to client_id coming from client_list, hinting at a workflow, but doesn't offer any exclusion criteria or alternative selection logic.

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 readOnlyHint annotation, it discloses key behavioral traits: pure analysis over injected data with 'no live pull', exact-value comparison semantics, and explicit truncation handling ('re-run with a higher limit when truncated is true rather than treating the list as complete'). This is rich, non-obvious context that an agent cannot get from 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-loaded with a [READ] marker and a one-line purpose before structured Args/Returns/Example sections. It is somewhat long, but the length is justified by the nested-object params and zero schema coverage; every section carries needed information.

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

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

No output schema exists, but the description fully enumerates the return dict (templateId, boundNetworks, driftedCount, compliantCount, driftedNetworks with per-setting deviations, returned/limit/truncated, note). Combined with the documented args and a worked example, an agent has everything needed 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?

With 0% schema coverage and nested objects, the description fully compensates: it documents the template shape {id, name, settings}, the networks row shape {networkId, name, boundTemplateId, settings}, the matching rule on boundTemplateId, and the limit default/truncation behavior. This is exactly what the schema lacks.

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+resource ('list drifted settings') and precise scope ('networks bound to a config template'), then explains the comparison semantics. It is clearly distinguishable from siblings like bind_network_to_template and unbind_network_from_template 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?

It establishes the context (networks bound to a config template, exact-value comparison) but never states explicit when-to-use vs when-not, nor names an alternative. Usage is implied by the 'only those whose boundTemplateId matches' clause rather than 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?

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds genuinely useful behavior beyond that: how results are bucketed by model prefix and, importantly, that the result carries 'returned'/'limit'/'truncated' and how to react to truncation. That pagination contract is real behavioral disclosure, though return-field details remain limited without an 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 one-line purpose followed by an Args block; every sentence carries information (bucketing behavior, defaults, truncation handling). No filler or restatement of the tool name.

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?

There is no output schema, yet the description compensates by describing the return shape (per-family counts, returned/limit/truncated flags) and the recovery path when truncated. Combined with per-parameter documentation, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: all four parameters are explained with semantics the schema lacks (org_id defaulting, model prefix with concrete examples like 'MS'/'MR46', limit default and truncation meaning, target defaulting). 'target' is explained only thinly ('Target name from config'), which keeps this from a 5.

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 ('Org device inventory'), the scope (organization-wide), and the optional filter dimension (model family). It also distinguishes itself from nearby siblings such as org_device_statuses and device_status by describing the bucketing-by-model-prefix behavior, so an agent can tell what this tool returns versus a status lookup.

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

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

Gives clear context for the optional args ('omit to use the target's default org', 'omit for all') and operational guidance for the truncation case ('re-run with a higher limit when truncated'). It does not name sibling alternatives or when-not-to-use conditions, so it stops 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?

Annotations already declare readOnlyHint=true, and the [READ] tag reinforces it without contradiction. The description adds genuine value by enumerating the four returned status values, which matters since there is no output schema. No auth or rate-limit caveats are mentioned.

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?

Purpose is front-loaded in the first line, followed by a compact Args block. No filler sentences; every line maps to a parameter or the core purpose.

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

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

For a simple read-only, single-device lookup with no output schema, the definition covers purpose, all parameters, and the possible return states. Only minor gaps remain around auth/permission expectations and what fields accompany the status.

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 carries the full burden and documents all three parameters: serial with a format example, org_id with meaning and default-omission behavior, and target with its source. The 'target' explanation ('name from config') is a bit thin but functional.

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 ([READ]) and resource ('One device's availability status') and enumerates the possible states (online/offline/alerting/dormant). The singular 'one device' scope implicitly distinguishes it from the bulk sibling org_device_statuses, though it never names the alternative.

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 guidance on when to use this versus alternatives such as org_device_statuses. The only conditional text ('omit to use the target's default org') is per-parameter behavior, not usage routing, so the agent must infer selection from the name alone.

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

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

Annotations already declare readOnlyHint=true, matching the [READ] tag, so safety is covered. The description adds useful scope (org-wide, WAN interfaces) but says nothing about result shape, pagination, or failure behavior. With annotations carrying the safety profile, a 3 is appropriate.

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 [READ] marker and a single tight purpose sentence, followed by a brief Args block. The Args section partially duplicates the schema, but it is small and each line adds default-behavior meaning rather than restating types.

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 two-optional-parameter read tool with no output schema, the description covers what it returns (uplink/WAN statuses) and how to scope it (org_id, target). Nothing critical is missing, though return format and pagination are unstated.

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, and it does: both parameters (org_id, target) are explained, including the non-obvious 'omit to use the default' fallback behavior that the bare anyOf/null schema does not convey. This is a solid lift over what the schema provides.

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

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

States a specific verb+resource: reads appliance/gateway uplink (WAN interface) statuses, scoped across the org. The [READ] tag reinforces the operation. It does not explicitly distinguish itself from nearby siblings like network_traffic, device_status, or uplink_loss_and_latency_rca, so the differentiation is only implicit.

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 when-to-use guidance or alternatives are offered. The description never says when to reach for this versus uplink_loss_and_latency_rca or device_status, both of which concern device/uplink health. Usage must be inferred from the purpose statement alone.

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 readOnlyHint=true (reinforced by the [READ] tag), but the description adds genuinely useful behavior beyond that: the result carries 'returned'/'limit'/'truncated' and the caller is told to re-run with a higher limit when truncated, rather than treating a short list as complete. It stops short of stating auth requirements or rate limits.

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

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

The one-line summary is front-loaded and the Args block is compact. The Args lines restate schema keys, but each adds substantive meaning (source, defaults, truncation semantics) rather than repeating types.

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

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

Despite no output schema, the description explains the shape of the list response (counts plus truncation flags), which is what an agent needs to consume results safely. It doesn't describe alert contents or severity levels, a minor gap for a 3-param read 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?

With schema coverage at 0%, the description carries the burden and mostly does: it identifies network_id's source (network_list), gives limit's default (200) and its interaction with truncation, and explains target as a config name with a default fallback. 'Target name from config' remains slightly underspecified, keeping this from a 5.

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 ('Current network health alerts') and scope ('summarised by severity'), which cleanly separates it from siblings like network_traffic and network_health_score. An agent can tell what it returns 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?

No when-to-use or when-not-to-use guidance, and no alternative sibling is named despite several overlapping candidates (network_health_score, network_traffic, overview). 'Current' implies recency but nothing routes the agent here versus those tools.

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

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

The readOnlyHint annotation already establishes that this is a safe read, so the '[READ]' prefix is largely redundant. The description does add value by disclosing what is returned (name, product types, timezone, bound template), a useful behavioral hint beyond the annotations, but it says nothing about permissions, rate limits, or error behavior.

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

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

Compact and front-loaded: the one-line purpose precedes a short Args block with no wasted wording. It is terse to the point of being slightly clipped, but every line earns its place.

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

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

For a simple two-param read with no output schema, the description covers both parameters, names the id source, and enumerates the returned fields, so an agent has enough to invoke it correctly. Minor gaps (auth/target semantics beyond 'default') keep it just under full marks.

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

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

Schema description coverage is 0%, so the description carries the full parameter burden and does so reasonably: network_id is defined as a Meraki network id with its source (network_list), and target is defined as a config target name with 'omit for the default'. Neither param gets format/validation detail, keeping it from a 5.

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 ('One network by id') and even enumerates the returned fields (name, product types, timezone, bound template), which clearly separates it from the list-oriented siblings. The distinction from network_list is implied by the parenthetical id source rather than stated outright, so it stops short of a 5.

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

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

Usage is only implied: the 'from network_list' note establishes the id prerequisite chain, and 'omit for the default' explains one param's behavior. There is no explicit when-to-use/when-not guidance or named alternative for fetching broader network data.

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 only provide readOnlyHint=true; the description adds explanation of the computation (weighted 0.5/0.3/0.2 across online %, uplink health %, alert penalty), that components are returned for explainability, and that it's pure analysis with no live pull. Good disclosure beyond annotations; doesn't cover auth or rate limits.

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

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

Front-loads the [READ] tag and one-line summary, then details weights, args, and return shape. Slightly long but every section carries distinct information; the arg-by-arg breakdown is well organized.

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

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

Given no output schema, the description documents the return dict fields (networksEvaluated, fleetScore, summary buckets in {}, weights, worst list fields, returned/limit/truncated/note). With 4 params, 1 required, and 0% coverage, this is thorough.

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

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

Schema coverage is 0%, so the description fully carries parameter documentation: shape of each row for device_statuses, uplinks, and alerts (including how 'active/ready' and severity values are interpreted), plus the limit/truncated semantics. This is exactly the compensation required when the schema is silent.

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

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

States a specific verb-class ('composite fleet health score per network') with concrete units (0-100) and ordering rule (worst-first). Distinguishes itself from raw-data siblings like org_device_statuses and device_status by naming this as a fold/aggregation over injected rows.

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?

Clearly points to the upstream source for the primary argument ('e.g. from org_device_statuses' devices'). Notes it operates on injected rows rather than live data, and explains when to re-run with higher limit when truncated. Doesn't explicitly say when NOT to use it (e.g. for single-network diagnosis vs network_list + device_status).

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?

readOnlyHint=true already declares the safety profile, so the '[READ]' tag is largely redundant. The description does add value by naming the returned fields, but omits pagination, result-size limits, and whether the listing is filtered by product type. With annotations covering safety, a 3 fits.

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 args lines, no filler, with the core purpose front-loaded in the first clause. The 'Args:' block is slightly ceremonial for two optional parameters but not wasteful.

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 no output schema, the description compensates by naming the returned fields, and both params are at least addressed. What is missing is any note on list size, pagination, or whether productTypes reflects a filter — minor gaps for a simple read-only listing tool.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning — and it partially does: org_id is defined and its default behavior explained, as is target. However 'Target name from config' is circular and never says what a target actually is or how it relates to org_id, leaving the second parameter only superficially documented. Baseline for two fully explained params would be 4; the vagueness on target holds it to 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?

The verb and resource are explicit ('[READ] Networks in the organization') and the parenthetical enumerates the returned fields (id, name, productTypes, tags), so an agent knows this is an org-wide network listing rather than a single-network fetch. It does not explicitly name the sibling network_get to distinguish list-vs-get, so it falls short of 5.

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

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

The only usage context is scoping: 'omit to use the target's default org' and 'omit for the default.' That tells the agent how to call it, but nothing about when to prefer it over network_get, network_vlans, or the org-level listing siblings. Usage is implied by the name rather than stated.

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

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

Annotations already declare readOnlyHint=true, but the description adds real behavioral context beyond them: the return payload carries 'returned'/'limit'/'truncated' and truncation must be handled by re-running rather than assuming completeness. It does not cover auth/permission needs, but the truncation contract is the important disclosure for a paginated read.

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?

Purpose is front-loaded in one line, then parameters are laid out in a scannable Args block. Nothing is padded; the note about 'truncated' is the one longer sentence and it directly affects correct usage.

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 no output schema, the description compensates by naming the returned metadata fields and explaining how to react to truncation. It is nearly complete for a read-only list tool; minor gaps remain around what identifiers the app rows carry, but nothing prevents a correct call.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: network_id provenance, timespan bounds and default (7200..2592000, default 86400), limit default plus truncation semantics, and target's fallback behavior. Each parameter gains meaning absent from the bare 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 first line states a specific verb and resource: '[READ] Application/protocol traffic mix for a network, top apps by bytes.' It is immediately distinguishable from siblings like client_usage, network_health_score, or device_uplinks, which measure different things.

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 gives useful invocation guidance (network_id comes from network_list; re-run with a higher limit when 'truncated' is true; omit target for the default), but never says when to choose this tool over adjacent ones such as client_usage or network_alerts.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description reinforces this with the [READ] tag and lists returned fields, but discloses nothing about permissions, rate limits, or pagination.

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 [READ] marker and resource, then an Args block. Every line earns its place; only the empty title line adds nothing.

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 two-parameter read tool with annotation-covered safety and no output schema, the description supplies the essential return fields, parameter provenance, and the target default. Pagination or result-count behavior is the only minor omission.

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

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

Schema coverage is 0%, so the description must compensate, and it does: network_id is described as a Meraki network id sourced 'from network_list', and target is described as a config target name whose omission selects the default. This adds real meaning beyond the bare schema.

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

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

States a specific verb via the [READ] marker and a specific resource (Appliance VLANs configured on a network), plus the fields returned (id, subnet, appliance IP). The [READ] prefix separates it from the write sibling update_network_vlan, though that sibling is never named.

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 or when-not guidance, and no alternative is named despite update_network_vlan being the obvious companion. The only contextual hint is 'omit for the default' for the target parameter.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the '[READ]' marker largely repeats that. The description does add value by disclosing the returned fields (name, email, access level), but says nothing about auth requirements, rate limits, or pagination.

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 and the returned fields before the arg list. The Args block is slightly verbose but every line adds meaning and nothing is wasted.

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 two-parameter read tool with no output schema, the description covers purpose, both parameters, and the shape of returned data, which is sufficient for correct invocation. Minor gaps (auth, pagination) remain but are not blocking.

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

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

Schema coverage is 0%, so the description carries the burden, and it does: it explains org_id (Meraki organization id, default org if omitted) and target (config target name, default if omitted). Both parameters and their defaulting behavior are documented, though format examples are absent.

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/read) and resource (dashboard administrators for the org) and even names the returned fields (name, email, access level). It is clearly distinguishable from siblings like org_list or org_get, though it never explicitly contrasts itself with them.

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 gives per-parameter guidance (omit org_id/target to fall back to defaults), which is useful operational context, but offers no explicit when-to-use-this-vs-an-alternative guidance and no 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?

The readOnlyHint=true annotation already carries the safety profile, and the '[READ]' prefix merely restates it. The description does add useful context about what the payload contains (response-code counts and 429 rate-limit data). However, it says nothing about pagination, time window, or rate-limit/auth behavior of the call itself.

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

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

The definition is short and front-loaded, leading with the '[READ]' scope marker and the overview before the Args block. Every line carries information, with only the redundant '[READ]' tag arguably duplicating the annotation.

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, no-required-parameter read tool with no output schema, the description covers both parameters, their defaults, and the returned content. The absence of any mention of time range or result shape is a small gap but not blocking.

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 carry the parameters, and it does: org_id is documented as the Meraki organization id with the omission behavior (use the target's default org), and target as a config target name defaulting to the default. It adds the important default-on-omission semantics, though it does not specify the org_id 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 states a specific verb and resource — an org API-request usage overview — and enumerates the returned content (response-code counts, 429 rate-limits). It is immediately clear what the tool does. It does not name or differentiate against any sibling, but no sibling tool overlaps this domain, so the omission is minor.

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 statement of when to use this tool versus alternatives, nor any prerequisites or exclusions. Usage is only implied by the tool name and the '[READ]' marker. An agent gets no routing guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes further by disclosing pagination behavior: the result carries 'returned'/'limit'/'truncated', and the agent is told to re-run with a higher limit when truncated rather than trusting an incomplete list. That is genuine behavioral context beyond structured fields, though nothing is said about auth requirements or rate limits.

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

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

The roll-up scope is front-loaded in a single line, followed by a compact args block. Every sentence earns its place, including the truncation warning, which conveys non-obvious retry semantics rather than padding.

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?

There is no output schema, and the description usefully compensates by naming the return envelope fields and their meaning. For a read-only tool with three optional parameters it is essentially complete; it could still say what status values or product types to expect, which is the only remaining gap.

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

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

Schema description coverage is 0%, so the description carries the full burden—and it does: org_id (Meraki org id, omit for default org), limit (default 500, drives truncation), and target (config name, omit for default) are all explained with defaults and semantics. This fully compensates for the empty 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 states a concrete verb and resource—org-wide device availability—and adds scope qualifiers ('rolled up by status + product type') that make it clearly distinct from the single-device sibling 'device_status'. It does not explicitly name that sibling, so it stops short of the 5 calibration case, but the aggregation scope alone is enough for an agent to differentiate.

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?

Guidance is limited to argument-level mechanics ('omit org_id to use the target's default org', 'omit target for the default'). It never states when to prefer this tool over 'device_status' or other org-level siblings, so usage is implied rather than stated.

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?

readOnlyHint=true already covers the safety profile, so the bar is lower; the description still adds value by naming the fields returned and documenting the default-resolution behavior when org_id/target are omitted. It does not describe error behavior when an id is not found, which is the main remaining 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?

Two short sentences plus a tight Args block; the read nature and resource are front-loaded and no sentence 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 two-parameter read tool with no output schema, the description supplies the return fields, parameter meanings, and default fallbacks, which is close to complete. Missing only edge-case/error behavior and an explicit pointer to the sibling list 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 0% and both parameters are undocumented in the schema, so the description carries the burden and does so: it defines org_id as the Meraki organization id and target as a config target name, plus the default behavior for each. It stops short of giving an id format or example.

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 ('One organization by id') and enumerates the returned fields (name, url, api access, cloud region). It implicitly distinguishes itself from the sibling org_list by emphasizing a single org, but never names the alternative explicitly.

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

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

The description explains how to fall back to defaults ('omit to use the target's default org'), which is useful context, but it never states when to pick org_get over org_list or org_licensing, leaving the alternative-selection decision 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?

readOnlyHint=true already establishes the safety profile, so the '[READ]' prefix is largely redundant. It adds modest value by disclosing the shape of the returned data, but says nothing about auth requirements, rate limits, or how per-device-type counts are scoped.

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 one-line purpose followed by a compact Args block; every line carries information. Slightly padded by the redundant '[READ]' marker.

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-required-param read tool with no output schema, the description covers purpose, both parameters, and default behavior adequately. Only auth/error behavior and return format details are 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 description coverage is 0%, so the description must carry the burden, and it does: both params are explained with their fallback behavior (omit org_id to use the target's default org; omit target for the default). That is real semantic value beyond the bare anyOf string 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?

States a specific resource (org licensing) and enumerates what the overview contains: status, expiration, per-device-type counts. It is clearly distinguishable from sibling reads like org_get or org_list, though it does not explicitly name them.

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 '[READ]' tag and 'overview' framing imply this is the tool for checking an organization's licensing state, but there is no explicit when-to-use, when-not-to-use, or alternative (e.g., org_get) guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data. The description adds the meaningful scope constraint that results are limited to organizations visible to the API key, plus the shape of each returned record, but says nothing about pagination, result size, or error behavior.

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

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

Two short lines, front-loaded with the read marker, scope, and returns before the argument block. Nothing is padded; every clause carries 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?

There is no output schema, but the description compensates by naming the returned fields. Combined with annotations covering read-only safety for this zero-required-parameter tool, an agent has enough to invoke it correctly; the only gap is the unstated relationship to org_get.

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 must carry the parameter. It does explain that 'target' is a Target name from config and that omitting it uses the default, which is more than the bare schema with default null provides. It does not clarify valid target values or where the config lives.

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 organizations) plus the scoping condition (visible to the API key) and the summary fields returned (id, name, url, apiEnabled). It implicitly separates itself from the single-object sibling org_get by enumerating list-level fields, but never names that sibling, so the differentiation is not explicit.

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

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

"[READ]" and "visible to the API key" give implied context for when this tool applies, and "omit for the default" guides the optional argument. However, there is no explicit when-to-use vs when-not guidance and no routing to alternatives such as org_get for a single organization.

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 [READ] marker is consistent with readOnlyHint=true, so no contradiction, but it is redundant with the annotation. The description adds that this is a one-shot aggregate (network + device rollup), which is useful scope context, yet it says nothing about auth requirements, pagination/rate limits, or result shape. With annotations covering the safety profile, a 3 is appropriate.

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 operation and its scope, then the triage guidance, then a compact Args block. Efficient overall, with only minor redundancy in the [READ] prefix duplicating readOnlyHint.

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

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

No output schema exists, so the description should ideally sketch return values; it hints at content ('networks + device status/product rollup') but not structure or aggregation level. Combined with the covered annotations and documented params, it is largely sufficient for triage-oriented calling.

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 carry the load, and it does document both parameters: org_id ('omit to use the target's default org') and target ('Target name from config; omit for the default'). The defaults-sourced behavior for 'target' is genuinely beyond the schema, though what constitutes a valid target is only loosely defined.

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 scope: a one-shot fleet health rollup combining 'networks + device status/product rollup'. This clearly distinguishes it from point tools like device_status, org_device_statuses, and network_traffic, which cover narrower slices.

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

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

Explicitly says 'Call this first to triage a Meraki organization before drilling into a specific network or device,' giving a clear ordering and context. It stops short of naming the specific alternative tools (e.g. device_status, network_get) or stating when not to use it, so it lands at 4 rather than 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 destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is partly covered. The description still adds real value beyond them: it discloses that prior status is captured for the audit trail, that the action is irreversible, and notably that no undo descriptor is offered even though an undo subsystem exists in this toolset. It stops short of describing failure behavior or permissions.

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

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

Front-loaded with the [WRITE][risk=high] tag and the core action, followed by consequences and then args. Every sentence contributes, though the audit-trail sentence is slightly explanatory and could be tightened.

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 destructive three-parameter mutation with no output schema, the definition covers irreversibility, dry-run preview, audit behavior, and all parameter meanings. Edge cases such as permission requirements or post-reboot state verification are left unstated.

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 carry the parameter burden, and it does: all three parameters are documented, including that target is a config name and that omitting it selects the default. The meanings added go beyond the bare 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?

States a specific verb and resource ('Reboot a device') with an explicit risk marker, so an agent can distinguish it from sibling mutations like update_device or blink_device_leds at a glance. The parenthetical '(no safe inverse)' further sharpens what kind of reboot this is.

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 an actionable hint to use dry_run=True to preview, which is genuine usage guidance. However, it never states when to prefer this over sibling tools such as blink_device_leds or update_device, nor when a reboot is inappropriate, so context is only implied.

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 flag destructiveHint=true, but the description adds the crucial detail the annotation cannot convey: undo restores membership only, and the device returns unconfigured with defaults, losing name, tags, address, notes and switch-port settings. It also discloses the dry_run preview affordance.

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 [WRITE][risk=high] and the core action, and the warning about lost configuration appears before the Args block where it matters. The Args section restates dry_run and serial/serials guidance already given in prose, which is mild redundancy.

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

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

For a destructive 5-parameter mutation with no output schema, the description covers what is destroyed, what is preserved, prerequisites, preview mode, and the undo relationship to a sibling tool. Nothing an agent needs to call this safely 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 0%, so the description carries the full burden, and it documents all five parameters including the serial/serials mutual exclusivity and dry_run behavior. The only weak spot is 'target: Target name from config', which is vague about what a target actually selects.

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?

Opens with a specific verb+resource ('Remove device(s) from a network') and immediately distinguishes itself from the sibling claim_devices_into_network by declaring itself its inverse. An agent can route correctly without opening 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?

Explicitly directs the agent to read device_status / switch_ports first when the pre-removal configuration will be needed, explains the undo path and its limitation, and notes dry_run=True as a preview mechanism. This is when-to-use, prerequisite, and safety guidance all in one.

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?

readOnlyHint=true already declares the safety profile, so the '[READ]' prefix is largely redundant with structured data. Beyond that, the description says nothing about what configuration data is returned, whether the serial must belong to a switch, or any permissions/rate-limit considerations. The one genuinely new detail is that omitting target yields the default target.

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 in a single sentence followed by a compact Args block; there is no filler. The docstring-style 'Args:' formatting is slightly heavier than a prose sentence would be but not wasteful.

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 two-parameter read tool this is nearly adequate, but with no output schema the description leaves the return value entirely unexplained and gives no hint about the shape or size of the port configuration payload. It is minimally viable rather than 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 description carries the full documentation burden, and it does so for both parameters: serial is qualified as an MS switch serial (narrowing the accepted input), and target is explained as a config name with an explicit default fallback. This is meaningful added semantics, though it doesn't state the format or allowed values of a target name.

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 resource ('Switch (MS) port configuration') and the keying parameter ('by serial'), and the [READ] tag disambiguates the ambiguous verb 'Switch' as a retrieval rather than a mutation. It does not differentiate itself from siblings such as device_uplinks or network_vlans, which an agent might reasonably confuse it with.

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 supplies no when-to-use context, no prerequisites (e.g. that the device must be an MS switch), and no alternative tool to prefer. The only guidance is the parameter-level note to omit target for the default, which is invocation detail rather than usage guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the write/destructive nature is covered. The description adds genuine value beyond that: the [risk=high] marker, the side effect that it captures the prior template binding for undo, and the dry_run preview affordance. It doesn't describe what happens to the network's config once unbound.

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 [WRITE][risk=high] tag and the core purpose, followed by undo semantics and a clean Args block. Every sentence carries information 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 destructive, non-idempotent mutation with no output schema and undocumented parameters, the description supplies the risk level, reversibility path (undo rebinding), preview option, and all param meanings. Only the post-condition state of the network is left implicit.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it documents all three parameters: network_id, dry_run, and target ('Target name from config; omit for the default'). The guidance on omitting target adds meaning the bare schema does not.

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: 'Unbind a network from its config template.' It even names the inverse operation ('rebind') and points at undo behavior, so an agent can distinguish it from bind_network_to_template and the undo_* siblings immediately.

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 gives clear when-to-use context (unbinding, with rebind as the inverse and undo rebinding to the captured template), and flags dry_run for previewing. It stops short of explicitly naming the sibling tools (bind_network_to_template / undo_apply) as the routing alternative, so it is strong but not fully explicit.

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?

Goes beyond the annotations by disclosing that the inverse executes through its own governed tool (so the real risk tier lives there), that dry_run previews the inverse tool and params, and that a token is single-use. These are meaningful operational facts; only failure behavior and return shape are left unspecified.

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 one-line summary, followed by a tight behavioral paragraph and an Args block that substitutes for the undocumented schema. Slightly longer than strictly necessary for a 3-param tool, but each sentence adds information.

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

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

No output schema exists and annotations only carry the safety profile, so the description usefully covers sourcing the token, previewing, and single-use semantics. It stops short of describing what is returned on success or how partial/aborted inverses behave.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: undo_id is sourced from undo_list or an _undo_id field, dry_run previews the inverse call without executing, and target is passed through only when the inverse tool accepts one.

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 ('Apply a recorded undo by dispatching its inverse tool') and marks the operation class as [WRITE] with risk=medium. It is clearly distinguishable from the read-only sibling undo_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?

Explicitly points to undo_list (and _undo_id in write results) as the source of the id, and tells the caller how to preview via dry_run=True. It does not state when *not* to use it or what to do if the token was already consumed, beyond noting a token applies only once.

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 only declare readOnlyHint=true; the description adds substantial context beyond that: `truncated` is measured (an extra row is fetched), `effectVerified` flags where the original write lost its response so the reversal is PROBABLE not confirmed, and `target` is accepted but unused. That is genuinely useful behavioral guidance, though it doubles as design rationale rather than pure operator 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 the core purpose, then the truncated/effectVerified caveats, then a compact Args block. Mostly tight, though the 'measured, not guessed' justification paragraph runs longer than strictly needed for an agent to act on.

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

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

No output schema exists, and the description compensates by naming the return fields ('original tool, the inverse tool, a human note', `undoId`, `effectVerified`, `truncated`) and their semantics. For a zero-required-param read tool this is complete enough to call correctly.

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

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

Schema coverage is 0%, so the description must carry both params — and it does: `limit` ('max rows, default 50') and `target` ('Unused... accepted for CLI uniformity'), the latter saving the agent from trying to use it. Defaults were already in the schema, so it is not fully additive, but the gap is well covered.

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?

Specific verb+resource: 'List recorded, not-yet-applied undo tokens (most recent first)'. The [READ] tag and 'not-yet-applied' scoping distinguish it clearly from the sibling undo_apply, which it explicitly references. An agent can tell the two apart without opening 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?

States the follow-on path: 'Use the `undoId` with `undo_apply`', routing the agent to the sibling. It also gives an important conditional: if `effectVerified` is False, check live state before applying. It stops short of explicit when-not-to-use-this (e.g., use undo_apply instead when you already have a token), but 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?

Annotations already declare readOnlyHint=false and destructiveHint=true, but the description adds substantial behavioral context: it captures prior values of changed keys to record an undo and a faithful audit trail, labels itself [WRITE][risk=medium], and offers a dry_run preview. This goes well beyond what the structured annotations 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?

The description is front-loaded with [WRITE][risk=medium] and the core operation, then layers in behavioral and parameter details without waste. The Args section is justified because the schema itself has no field descriptions.

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

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

For a non-idempotent, destructive write tool with a nested attrs object, no output schema, and zero schema description coverage, the description supplies the missing pieces: safety framing, preview path, undo/audit behavior, and all four parameter meanings. Nothing an agent needs to invoke 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 0%, so the description must compensate, and it does: it documents serial, attrs with an explicit list of allowed keys (name, tags, address, notes, lat, lng, floorPlanId), dry_run's preview behavior, and target's default behavior. This meaningfully compensates for the undocumented nested object.

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

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

The description states a specific verb and resource: 'Update device attributes (name/tags/address/notes).' It is clearly a mutation tool for device attributes, distinct in kind from siblings like reboot_device or device_status, but it never names a sibling alternative to sharpen the boundary.

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 verb and framing, and it does mention 'Pass dry_run=True to preview,' which is operational guidance. However, it never says when to choose this over related siblings such as undo_apply or other update tools, so the guidance remains implicit rather than explicit.

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=false and destructiveHint=true, so the write/destructive nature is covered structurally. The description adds genuinely new context: it captures changed keys' prior values and that undo restores them (consistent with the sibling undo_list/undo_apply), plus the dry_run preview path. It stops short of describing failure behavior or response shape, but adds real value beyond the annotations.

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

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

Front-loads the write/risk tag and the key behavioral fact (prior-value capture + undo), then a clean Args list. Every line is relevant. Minor redundancy between the top-line 'capturing its prior values' and the parenthetical 'undo restores them,' but overall tight.

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 5-param mutation with no output schema, the description covers purpose, reversibility, preview, and per-parameter meaning. The only gap is the return value on success/failure, which is not addressed, but with no output schema and strong parameter coverage the definition is largely complete.

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

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

With 0% schema description coverage and a nested free-form attrs object, the description carries the full burden and does: it names all five parameters and critically enumerates the allowed attrs keys (name, subnet, applianceIp, groupPolicyId, dhcpHandling), which the schema does not. This is exactly the compensation needed for an under-documented nested object.

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 ('Update an appliance VLAN') and adds a scope/tag marker ([WRITE][risk=medium]) that instantly separates it from read siblings like network_vlans or overview. An agent can identify the operation and its mutation nature 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?

It gives actionable invocation guidance — pass dry_run=True to preview, and omit target to use the default — but never states when to choose this over alternatives or any preconditions/exclusions. Usage is implied through the preview hint rather than explicitly framed as when/when-not.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds useful context beyond that — default degradation thresholds, the 'every ranking carries its numbers, not a black-box verdict' guarantee, and explicit truncation handling via returned/limit/truncated. This meaningfully informs how the agent should interpret and re-run results.

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 verb/scope sentence before the details, and each sentence carries content (scope, ranking method, output contract, param docs). Slightly verbose in repetition of defaults already implied, but no filler.

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

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

With no output schema and no annotation detail beyond readOnlyHint, the description carries the full burden and delivers it: it documents the return dict keys (uplinksEvaluated, degradedCount, thresholds, worst[...] with cause/action, truncated) and the analysis-vs-live input modes.

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%, yet the description documents all six parameters: loss_pct and latency_ms defaults, the nested shape of records ({serial, networkId, uplink, ip, timeSeries:[{lossPercent, latencyMs}]}), org_id/target defaults, and limit semantics. This fully compensates for the empty schema.

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

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

States a specific verb (rank), resource (MX WAN uplinks), and scope (loss + latency), plus the composite-ranking and cause/action enrichment. An agent can distinguish this from device_uplinks or network_health_score 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?

Explicitly routes between the two operating modes: 'Pass records for pure analysis, or an org/target to pull live.' That is real usage guidance. However, it never names an alternative sibling tool or says when NOT to use this RCA (e.g. vs. device_uplinks), so it falls short of full when/when-not 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?

readOnlyHint=true already covers the safety profile, and the description is consistent with it via the [READ] tag. It adds the useful fact that the response contains number, name, and enabled, but says nothing about pagination, result size, or auth/permission needs beyond the annotation.

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 one-line summary followed by a compact Args block; nothing is padded. The 'Target name from config' line is the weakest, since 'config' is never defined, but overall the text is tight and well ordered.

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 two-parameter read-only tool with no output schema, the definition covers both parameters and sketches the return fields. The main gap is that 'target/config' is introduced without explanation, leaving the non-default path ambiguous.

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

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

Schema description coverage is 0%, so the description carries the full burden and mostly meets it: network_id is identified as a Meraki network id sourced from network_list, and target is explained as a config target that defaults when omitted. The notion of 'target'/'config' is still somewhat opaque, so it falls short of fully compensating.

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

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

The description states a specific resource (Wireless MR SSIDs configured on a network) and enumerates the returned fields (number, name, enabled), with a [READ] marker signalling a list/read verb. It does not name a sibling to differentiate against, but no sibling covers SSIDs, so confusion risk is low.

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 only implied: the network_id arg points at network_list as the source, which tells the agent where the id comes from, and the target arg says to omit it for the default. There is no explicit when-to-use versus when-not, and no alternative tool is named.

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