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

Annotations already declare readOnly/idempotent/non-destructive, so the 'never changes anything' line is partly redundant, but the description adds genuine behavioral context: worst-first ranking, per-code summary, and that connectivity is only assessed when the fleet index supplies it. No permission or rate-limit detail, but the added nuance is real.

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?

Three sentences, front-loaded with the core action, then output shape, then safety posture, then input modes. No filler and nothing an agent needs is buried.

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-value burden and does so (findings ranked worst-first, per-code summary). Combined with the complete input schema and annotations, an agent has everything needed to invoke and interpret this tool.

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

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

Schema description coverage is 100%, so every parameter is already documented, including mutual exclusivity of query vs thing_names and the per-thing cost of include_certificates. The description only echoes the list-or-query choice, so the baseline 3 applies.

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

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

Specific verb (diagnostic sweep) plus resource (things/fleet) and an explicit enumeration of what is checked: shadow freshness, convergence, certificate status/expiry, connectivity. It clearly distinguishes itself from siblings like search_fleet_index (selection only) and inspect_thing_certificates (certificates only).

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 two accepted input modes (explicit thing_names list or fleet-index query) and that findings come back ranked, which tells the agent when this is the right call. It does not, however, explicitly contrast with sibling diagnostics or state when NOT to use it.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds real value beyond that by disclosing output behavior — that it lists only the differing fields — which is what an agent needs to interpret the result as a drift signal.

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

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

Two sentences, front-loaded with the verb and scope, with the rhetorical framing sentence earning its place by supplying the use case. Slightly more prose than strictly necessary, but 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 read-only, idempotent diff tool with full schema coverage and no output schema, the description covers what the tool returns (only differing fields) and when it helps. The main remaining gap is that it does not explain the section default or how named vs classic shadows are chosen, though the schema covers both.

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

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

Schema coverage is 100%, so the schema already documents all five parameters including the section enum and shadow-name omission semantics. The description mentions comparing reported state but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (structural diff) and resource (reported state of two things or two named shadows of one thing), which an agent can immediately distinguish from the single-target get_device_shadow. It stops short of naming that sibling explicitly, so it is clear but not fully differentiated within the fleet.

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 concrete when-to-use framing ("what is different about the one that misbehaves?" and "fleet-wide config drift"), which tells the agent the diagnostic scenario this tool serves. No explicit when-not or named alternatives are provided, so it is context without 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?

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuine diagnostic context by framing the tool as a disambiguator between 'no matches' and 'not indexed', though it says nothing about cost, latency, or auth requirements.

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

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

Two sentences with zero filler; the 'what it reports' clause comes first and the troubleshooting guidance second. Every clause 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?

With no output schema, the description still tells the agent what it will learn (enabled flag plus active modes) and why that matters in a workflow. Complete for a zero-argument diagnostic probe.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain and no schema gaps to compensate for. Baseline of 4 applies for a no-argument tool.

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 (reports) and resource (fleet indexing configuration), and enumerates the modes it covers (registry, shadow, connectivity, named shadows). An agent can distinguish it from describe_* siblings and search_fleet_index without opening a schema.

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

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

Explicitly names the trigger condition: 'Call this first when search_fleet_index returns nothing or reports unknown connectivity.' It also names the sibling it complements and the diagnostic decision it enables, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds genuinely non-structured context: what each endpoint type is for, that resolution is per-account and per-region, and the practical failure mode this explains. It stops short of noting whether results are cached or how quickly endpoint changes propagate.

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?

Three sentences, front-loaded with the return value, then the endpoint taxonomy, then the operational implication. Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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-parameter, read-only lookup with no output schema, the description supplies what the tool returns (endpoint addresses) and the scoping rules (per account, per region), which is enough to call it correctly. It does not describe the shape of the returned object, though with no output schema that gap is minor.

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

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

Schema coverage is 100% and the single enum parameter is already documented, so the baseline is 3. The description goes further by explaining what the enum values mean in practice (data vs. jobs vs. credential provider) and that the data endpoint is the MQTT/HTTPS address devices connect to, which is meaningfully more than the schema's short enum labels provide.

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

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

States a specific verb and resource: 'Returns the account-specific IoT endpoint addresses.' It then decomposes the resource into its variants (data, jobs, credential provider), which makes the tool's scope unambiguous. It does not explicitly contrast itself with any sibling, but no sibling in the list covers endpoints, so differentiation is inherent 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?

The line about endpoints being per-account and per-region being 'the usual cause of "the device connects but nothing arrives"' implies a diagnostic use case (connectivity troubleshooting), but usage is only implied. There is no explicit when-to-use statement, no when-not-to-use, and no named alternative tool for any adjacent task.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds crucial context beyond them: it discloses the untrusted-data fence around attributes and explains why (any principal with UpdateThing can write them). This is real behavioral context about data trust and write reachability that annotations don't cover.

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

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

A single, dense sentence front-loads what the tool returns and then explains the one surprising trait (untrusted-data fencing). No wasted words, appropriate length.

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

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

For a two-param read tool with full schema coverage and no output schema, the description covers return contents and the key trust caveat. It doesn't mention things like error behavior for missing things or whether include_groups affects the groups field naming, but the core is solid.

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

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

Schema description coverage is 100%, so the schema documents both thing_name and include_groups (including the default). The description adds no parameter-level syntax or format detail beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb (Returns) and resource (registry record of one thing) and enumerates the exact fields returned (ARN, thing type, version, billing group, groups, attributes). This clearly distinguishes it from siblings like list_things (which enumerates) and get_device_shadow (which returns shadow state).

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

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

The description implies usage by naming the single-thing scope versus the list_things sibling, but it never explicitly states when to use this versus alternatives like get_device_shadow or why one would pick this tool. Usage is only implied by the resource described.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral value beyond them by surfacing the silent-message-loss semantics of a missing error action and noting the tool flags it — useful context an agent cannot infer from 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?

Two sentences, no filler. The return-shape enumeration is front-loaded and the second sentence earns its place by explaining a real operational hazard.

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 adequately covers the return shape by naming the fields returned. Annotations cover safety. The only gap is error behavior when rule_name does not match an existing rule, which is not addressed.

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?

Single required parameter with 100% schema description coverage ('Exact topic rule name'), so the schema already carries the semantics. The description adds nothing about name format, case sensitivity, or lookup failure behavior, so the baseline 3 applies.

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

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

Specific verb+resource ('Returns one topic rule in full') that also enumerates the exact payload: SQL, SQL version, each action with its write target, and the error action. The 'one' clearly differentiates it from the sibling list_topic_rules without needing 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?

Usage is implied by 'Returns one topic rule' (look up a single rule by name), but there is no explicit when-to-use, no mention of when-not to use it, and no routing to siblings such as list_topic_rules for enumeration. Minimum viable context, nothing misleading.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely new behavioral context: it returns staleness metrics, unconverged desired fields, and fences the raw document as untrusted data. That untrusted-data fencing is a security-relevant behavior not visible in annotations or 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?

Two sentences, front-loaded with the action and return shape, followed by the preference rationale. 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?

For a 3-param read-only tool with 100% schema coverage and annotations carrying the safety profile, the description is nearly complete. It covers return semantics, the untrusted-data fence, and the preference over raw reads. No output schema exists, so return-value explanation is appropriately placed in the description.

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

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

Schema coverage is 100%, so all three parameters (thing_name, include_raw, shadow_name) are already fully documented in the schema. The description mentions 'classic or a named device shadow' which maps to shadow_name, but adds no syntax or default details beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Reads) and resource (classic or named device shadow), and enumerates exactly what is returned: staleness, unconverged desired fields, raw document. Distinguished from sibling compare_device_shadows and list_named_shadows by being the single-thing read with analysis.

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 'Prefer this over reading the raw shadow yourself' and gives the reason (staleness and drift analysis is where the operational answer usually is). This is a clear when-to-use statement with an alternative named.

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 readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavioral content: it discloses exactly what is returned (certificates with status and expiry) and that inactive, revoked, expired and expiring-soon entries are flagged. It stops short of noting pagination or whether the check is point-in-time.

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 core behavior is front-loaded in one dense sentence. The second sentence about certificate expiry being a 'classic silent fleet outage' is motivational rather than operational and does not strictly earn its place, though it is brief.

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, single-parameter tool with no output schema, the description carries the return-value burden adequately by naming the listed fields and the flagged statuses. Nothing essential to correct invocation is missing, though the flag semantics (e.g., what 'expiring soon' means) remain undefined.

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?

Single parameter with 100% schema description coverage ('Exact AWS IoT thing name.'), so the schema fully carries parameter meaning. The description adds no syntax, format, or constraint detail beyond it, which is the correct baseline of 3.

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

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

States a specific verb and resource: lists the X.509 certificates attached to a thing, plus the fields returned (status, expiry) and the flagged states. The resource is clearly distinct from every sibling (describe_thing, list_things, get_device_shadow), so an agent can disambiguate 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?

Usage is only implied by the motivation sentence about certificate expiry causing silent outages; there is no explicit when-to-use, when-not-to-use, or named alternative (e.g., describe_thing for general thing metadata). An agent can infer intent but 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds a genuinely non-obvious AWS behavior: the classic shadow is excluded from results. It does not mention pagination or result ordering, which would be the remaining behavioral 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 tight sentences with zero filler. The primary behavior is front-loaded and the exclusion/alternative follows immediately.

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 leaves the return shape (a list of shadow names) and pagination unspecified. However, annotations carry the safety profile and the key semantic trap (classic shadow exclusion) is fully covered, so the definition is nearly complete for a simple one-parameter 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 description coverage is 100% for the single required parameter, so the schema already carries the meaning ('Exact AWS IoT thing name'). The description adds no format or constraint detail beyond it; baseline 3 applies.

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

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

Specific verb ('Lists') plus resource ('named shadows') plus scope ('that exist for one thing'). It immediately distinguishes itself from get_device_shadow by explicitly scoping to named shadows only.

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

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

Explicitly states when this tool does NOT apply (the classic unnamed shadow is never listed) and names the alternative tool and invocation pattern (get_device_shadow with no shadow_name). This is exactly the routing guidance an agent needs given get_device_shadow is a sibling.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety bar is covered. The description adds genuinely useful behavioral facts beyond that: the region scoping, newest-page-first ordering, and the constrained return shape (names and types only). It doesn't elaborate on page-size clamping or token expiry, which are only implied by the schema.

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

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

Three tight sentences, front-loaded with the core action and scope, then usage, then the return-shape caveat. Every clause carries information with no redundancy.

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

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

There is no output schema, so the description compensates by stating exactly what is returned ('names and types only') and where to get detail. Combined with annotations and full schema coverage, 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?

Schema coverage is 100%, so all five parameters are already documented in the schema, including the attribute_name/attribute_value dependency. The description restates the filter capability ('by thing type or by a single attribute name/value pair') but adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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 ('Lists AWS IoT things') with scope ('in the configured region') and ordering ('newest page first'). It explicitly distinguishes itself from the sibling describe_thing by noting it returns names and types only.

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 concrete use case ('discover thing names before inspecting a shadow') and routes to the sibling for detail ('call describe_thing for detail'). It stops short of naming when not to use it or listing other alternatives like search_fleet_index, so it is clear context without explicit exclusions.

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

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

Annotations already declare this a safe, read-only, idempotent, non-destructive, open-world operation, so the safety profile is covered. The description adds value beyond annotations by disclosing the shape of the result (topic filters plus a disabled flag), which matters since there is no output schema. It does not mention pagination behavior despite the paging params.

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 tight sentences, zero filler, with the scope and purpose front-loaded before the usage hint. Every sentence 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 listing tool with no output schema, the description covers purpose, returned fields, and the relationship to single-rule inspection, and annotations cover safety. The only gap is pagination/result-size behavior, which is relevant given the two paging parameters.

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

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

Schema description coverage is 0% and the description says nothing about the two parameters (next_token, max_results). Their names are largely self-explanatory, but the description does not compensate for the coverage gap with paging semantics, limits, or defaults.

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

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

States a specific verb and resource (lists the account's topic rules) and even names the returned fields (topic filter, disabled state). The phrase 'before opening a single rule' implicitly distinguishes it from describe_topic_rule, so an agent can route 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 a concrete use case ('answer where does telemetry from this topic go?') and positions it as the step before drilling into a single rule, which points at describe_topic_rule as the alternative. It stops short of naming that sibling explicitly or stating exclusions, so it is clear context rather than a full routing rule.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint). The description adds real behavioral context beyond that: results include connectivity state only when connectivity indexing is enabled, and the operation requires account-level fleet indexing to be enabled. It stops short of describing result volume 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?

Well front-loaded: purpose, then the unique use case, then syntax examples, then the prerequisite. Every segment earns its place, though the run-on example block is slightly dense to parse.

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

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

For a query tool with no output schema, the description covers what it returns, the key precondition, and query syntax. It is complete enough to invoke correctly, with only pagination semantics (next_token) left entirely to the schema.

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

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

With 67% schema coverage, the query and next_token parameters are documented in the schema, but the description adds substantive meaning for the query parameter via field:value syntax and four concrete examples (connectivity.connected, thingName wildcard, attributes.site, shadow.reported.firmware). max_results is left to the schema, which is acceptable.

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 ('Runs a fleet-indexing query (AWS_Things index)') and clarifies it returns matching things with connectivity state. It claims unique scope with 'only way to answer which devices are offline right now', which distinguishes it from plain listing siblings, though it never names list_things 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?

Explicitly frames the key use case ('which devices are offline right now') and states a hard precondition ('Requires fleet indexing to be enabled on the account'). It does not directly contrast with list_things or describe_thing, so the agent must infer when the simpler siblings suffice.

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