infrawise

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

Annotations only cover readOnlyHint and openWorldHint; the description adds substantial behavior the agent could not otherwise know: no AWS re-read happens on a tool call and dataHealth.withinRequestedAge reports freshness, ambiguous matches withhold `accesses`, unresolvedLambdas explains refused Lambda links with reasons, and candidateLambdas replaces an empty `triggers`. This is exactly the kind of context annotations do not carry.

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 opening sentence is well front-loaded, but the body runs long as an unstructured wall of conditionals covering every branch of the return shape. Each clause is informative, yet the density without formatting or grouping makes it easy to lose the primary purpose among the edge-case handling.

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 full burden and does so thoroughly: success shape (`matches` per file), the single-match shortcut, ambiguity, no-match, unresolved-Lambda, and not-found cases are all specified, plus the freshness caveat. An agent has enough to call it and interpret every plausible response.

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 `file` (path or trailing fragment, case sensitive) and `maxAgeSeconds` (advisory freshness tolerance) are already documented in the schema, and the description largely restates them. It does add the consequence chain around `file` values, but that is response behavior rather than new parameter meaning, 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?

States a specific verb and resource (analyze a named function/Lambda handler) and enumerates the exact findings: tables queried, scan vs query, queue publishing, secret access, trigger event shape. This is clearly differentiated from the sibling overview tools (get_lambda_overview, get_infra_overview), which are catalog-level rather than per-function.

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 prescribes the moment of use ('Call this before writing or reviewing a Lambda handler') and gives conditional guidance for the `file` parameter (pass it to bind to the file you are editing; re-call with `file` rather than guessing on ambiguity). No alternative tool is named, but no sibling performs this same analysis, so there is little to route against.

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 openWorldHint=false, so safety is covered. The description adds genuine behavioral context by disclosing that it enumerates ALL APIs across three protocol types and links each route to its Lambda, which is more than the annotations convey. The snapshot/freshness caveat lives in the parameter schema rather than the description, a minor omission.

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 return content and followed by usage scenarios. No filler; 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?

With no output schema, the description usefully explains the returned structure (routes, methods, paths, Lambda target). Annotations cover the safety profile and the sole parameter is fully documented, so an agent has enough to call it correctly. Only the freshness behavior, which is documented in the schema, is not echoed in the description.

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

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

Schema description coverage is 100% for the single maxAgeSeconds parameter, and the schema itself richly documents its freshness-tolerance semantics. The description adds no additional parameter meaning beyond what the schema provides, 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?

States a specific verb ('Returns') and resource ('all API Gateway APIs (REST, HTTP, WebSocket)'), then enumerates exactly what fields come back (routes, HTTP methods, paths, and the invoked Lambda). It is clearly distinct from siblings like get_lambda_overview or get_infra_overview because it names the API Gateway domain and its route-to-Lambda linkage.

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 two concrete when-to-use scenarios: 'before writing any API handler to understand which Lambda handles a route' and 'when reviewing API surface area and Lambda integration coverage.' This is clear context, though it doesn't name an explicit alternative tool or a when-not-to-use condition, keeping it below 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 openWorldHint=false, so safety is covered. The description adds real value beyond that: it clarifies that cached data is never read, warns of the TLS/rediss:// client-code implication, and discloses the costSignal annotation on clusters with more than 3 nodes.

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 — the highest-value content (what is returned, when to call) leads, and each sentence carries distinct information (fields, usage, data-exclusion, cost note). Three sentences with little waste, though the costSignal sentence is somewhat tangential.

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 overview tool with one optional param and no output schema, the description compensates by enumerating returned fields and disclosing behavior. An agent has enough to call it correctly and interpret the result; only the exact response shape 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 100% and the single optional maxAgeSeconds parameter is fully documented in the schema, so baseline is 3. The description adds no parameter information beyond what the schema already provides.

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

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

States a specific verb and resource ('Returns all ElastiCache clusters') and enumerates the exact fields returned (engine, version, node type, encryption status, failover state). This is clearly distinguishable from the sibling overview tools, which cover entirely different AWS services.

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

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

Gives concrete when-to-use conditions: 'Call this before writing cache client code' and 'when reviewing cache availability and security posture.' No explicit when-not or named alternative, but the service scope makes alternatives largely irrelevant.

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 openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: behaviors are returned in CloudFront match order with ordered behaviors first and the default last, and execute-api origins get their API Gateway name resolved. It stops short of stating any result-size 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?

One dense paragraph that front-loads the return contents before moving to usage guidance, so an agent gets the most important information first. Every clause carries content, though the single long sentence is slightly heavy 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?

With no output schema, the description carries the full burden of describing return shape and it does so thoroughly, including field-level detail and ordering semantics. It is nearly complete, lacking only edge-case notes such as result limits or how large distribution sets are handled.

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

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

Schema description coverage is 100% and the single maxAgeSeconds parameter is fully documented in the schema, including its advisory freshness semantics. The description adds nothing about the parameter, so the baseline of 3 applies since the schema does the heavy lifting.

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

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

States a specific verb (returns) and resource (all CloudFront distributions) and then enumerates exactly what is included per distribution: id, domain, aliases, origins, and each cache behavior with path pattern, target origin, cache policy, protocol and methods. This is precise enough to distinguish it from siblings such as get_cache_overview and get_api_routes.

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 three usage contexts: answering which distribution/behavior serves a path and which origin it hits, checking before changing a path-based routing rule, and reviewing edge caching/HTTPS enforcement. It gives clear when-to-use guidance but names no alternative sibling or explicit exclusion.

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 (readOnlyHint=true, openWorldHint=false), and the description adds real behavioral context beyond them: secret values are never returned, and SECRET_HASH must be sent when a client has a secret. It stops short of describing pagination or snapshot staleness mechanics in the description body 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?

Front-loads what is returned, then the usage trigger, then the exclusion. Dense but nearly every clause carries information; the enumeration of client fields is slightly long but justified since there is no output schema.

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

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

With no output schema, the description carries the burden of describing return content and does so thoroughly (MFA config, auth flows, OAuth scopes, callback URLs, token validity, secret presence). Nothing an agent needs to call it correctly appears missing.

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

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

Schema description coverage is 100%, and the single optional maxAgeSeconds parameter is fully documented in the schema including its advisory nature and refresh behavior. The description adds nothing about parameters, 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?

States a specific verb and resource ('Returns all Cognito user pools with MFA configuration and every app client config') and enumerates the returned facets, letting an agent distinguish it from sibling overview tools like get_secrets_overview or get_lambda_overview 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?

Explicit positive trigger ('Call this before writing any Cognito sign-in, sign-up, or token-refresh code') plus an explicit exclusion ('Do NOT call to look up users or tokens'). Both when-to-use and when-not are stated, not inferred.

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 openWorldHint=false, so safety and locality are covered without description support. The description adds value by disclosing the shape of the returned data (states, expressions, patterns, targets), but says nothing about auth requirements, rate limits, or freshness. 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?

Two sentences, both front-loaded: the return contents first, then the usage contexts. Every clause carries concrete information (field names, rule types) and there is 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?

With no output schema, the description correctly compensates by enumerating the returned fields, which is exactly what an agent needs to interpret results. Only one optional parameter exists and annotations cover the safety profile. The only minor omission is that the snapshot/staleness model lives solely in the schema, not 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?

There is a single optional parameter (maxAgeSeconds) and schema description coverage is 100%, so the schema fully explains its semantics, including the advisory freshness behavior and dataHealth reporting. The description does not mention it, but per the baseline rule, a 3 is correct when the schema already does the heavy lifting.

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

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

States a specific verb (Returns) plus resource (EventBridge rules) and enumerates the exact fields returned: name, ENABLED/DISABLED state, schedule expression, event pattern, and target Lambda names. This clearly distinguishes it from sibling overview tools like get_lambda_overview because it is scoped to EventBridge rules and their triggers.

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

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

Explicitly states when to call it: 'when checking what schedule or event triggers a Lambda, or when reviewing rule coverage across the account.' This gives two concrete usage contexts. It does not name a specific alternative tool or an exclusion condition, so it stops short of a 5, but the trigger conditions are clear and actionable.

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

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

Annotations already cover safety (readOnlyHint true, openWorldHint false), so the description correctly spends its space on the non-obvious caveat: gaps in dataHealth.codeCoverage mean missing edges never prove no runtime access. That is a genuinely useful epistemic limit not derivable from annotations, though it stops short of describing pagination, size, or shape of the payload.

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, zero filler: return contents first, then the critical caveat, then the usage/routing sentence. Front-loaded and 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?

With no output schema, the description carries the burden of describing return contents and does so by enumerating the four payload categories, plus it flags the coverage caveat. It could say more about payload volume or how findings are structured, but nothing needed to call it correctly is missing.

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

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

There is a single parameter and schema description coverage is 100%, with the schema itself carrying rich guidance on when to pass a small maxAgeSeconds versus omitting it. The description does not mention the parameter at all, 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?

The description names the specific contents returned (nodes, code edges, findings, unresolvedReferences) rather than restating the title, and it explicitly distinguishes itself from get_infra_overview. An agent can tell what this returns and how it differs from the sibling 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?

It gives both a positive condition ("when tracing relationships across services or inspecting the full finding set") and a routing rule to the alternative ("prefer get_infra_overview for quick orientation"). This is explicit when/when-not guidance against a named 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 only cover readOnlyHint=true and openWorldHint=false, and the description adds substantial behavior beyond that: the `configured` flag semantics (empty results when no infrawise.yaml is loaded), the `setupHint`, the fixed `dataHealth` shape with `analyzedAt`/`ageSeconds`/`iac`/`refreshWith`, and the crucial interpretation rule that a non-`ok` source means 'not read' rather than 'none exist'.

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 highest-value content (what it returns, then routing guidance) before the response-shape detail. It is dense at six sentences, and the dataHealth explanation is somewhat lengthy, but given there is no output schema most of it 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 and rich response semantics (configured flag, dataHealth block, per-source status interpretation), the description carries the return-value burden well and explains how to read an empty result. An agent can call this tool correctly and interpret its response without further context.

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

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

There is a single optional parameter with 100% schema description coverage, and the schema already documents the advisory freshness-tolerance semantics of `maxAgeSeconds` in detail. The description adds no parameter-specific meaning, so the baseline of 3 for high schema coverage 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+resource ('Returns a compact infrastructure snapshot') and enumerates what it contains (service counts, databases, queues, topics, secrets, lambdas, findings). It explicitly distinguishes itself from the sibling get_graph_summary, 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 an explicit trigger ('Call this first at the start of any database or infrastructure task'), names the alternative ('Prefer this over get_graph_summary'), and states the exact condition that selects the alternative ('use get_graph_summary only when you need every node, edge, and finding in full'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description adds substantial context: env var values are never returned, the costSignal is a config-level heuristic with no billing API, and unresolvedLink carries a reason enum (no_match/multiple_functions/multiple_lambdas) with the consequence that analyze_function returns no triggers. These are behaviors an agent cannot infer 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 returns and usage routing, then the edge-case details. It is long, but nearly every sentence carries non-obvious behavioral information. Slight density cost for an overview tool, though no sentence is clearly 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?

No output schema exists, but the description fully compensates by describing the return contents, the costSignal heuristic, and the unresolvedLink structure with its reason values and downstream effect. 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 description coverage is 100%, and the single maxAgeSeconds parameter is thoroughly documented in the schema itself (freshness tolerance, dataHealth.withinRequestedAge, the analyze refresh caveat). The description adds no parameter-specific meaning beyond the schema, 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?

States a specific verb+resource and enumerates exactly what is returned: runtime, memory, timeout, environment variable key names, and trigger event shapes. It explicitly distinguishes itself from the sibling analyze_function ('without running analyze_function'), so an agent can select it without opening a schema.

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

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

Gives explicit when-to-use conditions ('auditing Lambda configuration for default memory (128 MB) or high timeouts', 'need the trigger event shape for a specific function') and names the alternative it substitutes for (analyze_function). This is a textbook when/when-not with an alternative.

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 well beyond the readOnlyHint/openWorldHint annotations by disclosing the exact response semantics: errorCount is null, topErrorPatterns is empty, errorsObserved is false, and no message bodies are fetched. Since there is no output schema, this is the only place an agent learns how to interpret the response and why empty error fields must not be read as 'no errors'.

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 what is returned, then the legacy-name caveat, then usage guidance — a sensible order with no filler. There is mild redundancy between 'errorsObserved is false' and the later warning not to infer no errors, though the second occurrence serves a different (interpretive) 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?

With no output schema, the description still explains the returned fields and their placeholder values, the filtering parameter, and the key interpretive pitfall. Combined with full schema coverage and safety annotations, an agent has everything needed to call and read this tool correctly.

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

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

Schema coverage is 100% and both parameters are already well documented, including the advisory nature of maxAgeSeconds and the stale-snapshot behavior. The description only restates that logGroup filters names, adding no syntax or semantics beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource (returns CloudWatch log group names and retention metadata) with an explicit scope exclusion (without reading log events). It also disambiguates the misleading legacy name get_log_errors, so an agent can't mistake it for an error-diagnosis tool.

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

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

Gives an explicit positive trigger ('Call when checking retention policies') and explicit exclusions ('do NOT use to diagnose runtime errors or infer that no errors occurred'), plus guidance to use logGroup for filtering. Nothing about when to select or avoid this tool is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond annotations: 'Parameter values are never returned,' which tells the agent this cannot leak secrets. It does not cover pagination or size 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?

Three tight sentences, each doing distinct work: what is returned, what is excluded, and when to call it. The scope is front-loaded and there is 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, the description must convey the return shape, and it does: all parameters with type and tier, values omitted. Combined with annotations and a fully documented parameter, this is nearly complete; only ordering, pagination, or result-size behavior is unaddressed.

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 single parameter maxAgeSeconds is fully documented in the schema (100% coverage), including its advisory freshness semantics, so the description need not repeat it. The description adds no parameter-level information, which is the correct baseline of 3 when the schema carries the load.

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

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

States a specific verb ('Returns') and resource ('all SSM Parameter Store parameters'), plus the exact fields returned (type and tier). It is clearly distinguishable from neighboring tools like get_secrets_overview by naming the SSM Parameter Store domain, though it does not explicitly contrast with any sibling.

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

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

Explicitly states when to use it: 'checking which config parameters exist for a service or verifying parameter types.' That is clear context, but there is no when-not guidance or named alternative (e.g., get_secrets_overview) to route the agent away when appropriate.

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 readOnlyHint/openWorldHint, so safety is established, but the description adds real behavioral context: CloudWatch-derived oldestMessageAgeSec, the FIFO MessageGroupId requirement, and the 6x Lambda timeout rule of thumb. It doesn't cover output shape or pagination, but the added semantics clearly exceed 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-loaded with the return payload, then when-to-use, then the sibling alternative. Dense and largely waste-free, though the FIFO MessageGroupId aside is mildly tangential to selecting this tool.

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 enumerating returned fields and the optional runtime-signal field. Combined with when-to-use guidance and the sibling alternative, an agent has enough to call it correctly; only minor detail (e.g. multi-account scope) is absent.

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

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

Schema description coverage is 100% and the single maxAgeSeconds parameter is thoroughly documented in the schema itself (freshness tolerance, advisory behavior, dataHealth.withinRequestedAge). The description adds nothing about the parameter, 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?

States a specific verb ('Returns') and resource ('all SQS queues') and enumerates the concrete fields returned (DLQ presence, encryption, isFifo, visibility timeout, message count, retention). It explicitly contrasts with sibling get_infra_overview, so an agent can distinguish the two without opening schemas.

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

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

Provides explicit when-to-use triggers ('reviewing messaging architecture, investigating a message backlog, checking DLQ coverage, verifying visibility timeout') and names the alternative with its narrower scope ('Use get_infra_overview for a quick queue count only'). Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description still adds real boundary information beyond the annotations: security findings are included and object contents never are, which tells the agent what this tool will and won't report. It stops short of describing staleness behavior, though the schema parameter carries that.

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?

Four short sentences, each doing distinct work: what is returned, when to call, when not to call plus the alternative, and one scope boundary. The most decision-relevant content (the return inventory) is front-loaded.

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

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

There is no output schema, and the description compensates by enumerating the returned fields and the one thing never returned. Combined with the routing guidance and a fully documented parameter, an agent has everything needed to select and invoke this tool 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 100% and the single maxAgeSeconds parameter is thoroughly documented in the schema itself, including the advisory semantics and the analyze refresh note. The description adds no parameter-level information, 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?

States a specific verb and resource (returns all S3 buckets) and enumerates exactly what each entry carries: versioning, encryption, public access configuration, security findings. It also explicitly negates the closest sibling case by routing counts to get_infra_overview, so an agent can separate it from the other *_overview tools without opening a schema.

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

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

Gives three concrete triggering situations (checking which buckets exist, reviewing security posture, confirming a bucket name before writing upload/delete handlers) and an explicit exclusion with the named alternative for the count-only case. Both the when and the when-not are stated, 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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful provenance context the annotations cannot: referencedKeys are key names inferred from parsing application code and are never secret values. It does not restate the schema's freshness/snapshot caveat, which is the one behavioral element left to 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?

Two sentences, each doing distinct work: the first front-loads what is returned and what referencedKeys means, the second front-loads when to call it. No redundant phrasing or 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 single-parameter, read-only overview tool with no output schema, the description covers the resource scope, the returned fields, the semantics of the non-obvious field, and the calling conditions. 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 100% for the single optional maxAgeSeconds parameter, and the description adds nothing about it. Baseline 3 applies when the schema fully carries parameter documentation, and the description does not compensate with any extra semantics.

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

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

Specific verb (Returns) plus resource (all Secrets Manager secrets) and an enumeration of the returned fields (rotation status, rotation interval, referencedKeys). It is immediately distinguishable from sibling overview tools like get_parameter_overview or get_s3_overview, which cover different resources.

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

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

Gives three concrete when-to-use scenarios: checking which secrets exist, confirming rotation before a security review, and looking up the correct key name before writing code. Clear context, but it names no exclusions or alternative sibling tools, so it stops short of the top of the scale.

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 readOnlyHint and openWorldHint, so safety is already covered; the description goes further by disclosing the data provenance (parsed from local IaC files, not the deployed stack), the staleness model (CDK outputs carry stale:true and staleReason), and the remediation ('re-synthesizing'). This is meaningful behavioral context beyond the structured annotations.

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

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

The primary purpose is front-loaded in the first clause, followed by return fields, usage triggers, exclusions, and the staleness caveat. Each sentence carries distinct information with no redundancy or 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, the description compensates by naming the returned fields (name, description, export name, raw value expression) and the stale/staleReason flags. Combined with the annotation-covered safety profile and a fully documented lone parameter, an agent has everything needed to call 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 coverage is 100% and the single maxAgeSeconds parameter is fully documented in the schema, including the advisory-with-dataHealth.withinRequestedAge behavior. The description adds freshness framing but no syntax or format detail beyond what the schema already provides, 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?

States a specific verb and resource ('Returns all stack outputs and cross-stack exports') and enumerates the sources (Terraform output blocks, CloudFormation/CDK Outputs sections) and returned fields. It also explicitly scopes itself against live attributes ('outputs come from local IaC files, not the deployed stack'), so an agent can distinguish it from the resource-introspection siblings.

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

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

Gives explicit when-to-use triggers ('wiring cross-stack references (Fn::ImportValue, terraform_remote_state) or when you need the exported name of a resource defined in another stack') and an explicit when-not ('Do NOT call for live resource attributes'). This leaves nothing to inference for tool selection.

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 openWorldHint=false, so safety is covered. The description adds value by enumerating exactly what a caller receives (status, shard count, retention, encryption, capacity mode) even though no output schema exists, which is genuinely useful behavioral disclosure. It stops short of describing snapshot freshness or pagination in the tool description itself, though the schema parameter documents the cached-snapshot model.

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, all load-bearing: returns first, usage scenarios second, sibling disambiguation third. No filler, no repetition of the title, and the routing information is front-loaded rather than 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?

For a read-only lookup tool with no output schema, the description compensates by enumerating the returned fields for both stream types, and the schema fully documents the single optional parameter. Nothing an agent needs to select or invoke this 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 coverage is 100% and the single parameter (maxAgeSeconds) carries a rich description covering freshness tolerance, dataHealth.withinRequestedAge, and the need to run `infrawise analyze` to refresh. The tool description adds nothing about this parameter, so the baseline 3 for full schema coverage is appropriate.

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

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

The description opens with a specific verb and two named resources (Kinesis data streams and Amazon MSK clusters) and enumerates the concrete attributes returned for each (status, shard count, retention hours, encryption, capacity mode; state, cluster type, Kafka version, broker count). It also explicitly contrasts itself with the sibling get_topic_details, so an agent can distinguish the two streaming-related tools 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?

It gives concrete triggering scenarios ('writing Kinesis producer or consumer code', 'checking whether a stream is PROVISIONED or ON_DEMAND before writing PutRecord calls', 'reviewing streaming architecture') and names the alternative for a different case ('For Kafka topic-level producer/consumer mappings... use get_topic_details instead'). Both when-to-use and when-to-use-something-else are stated explicitly.

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 and openWorldHint, but the description goes much further: row data is never returned, index metadata describes possible access paths rather than observed query plans, found:false must be read against source health, and DynamoDB may carry an advisory costSignal. These are non-obvious behavioral traits an agent could not infer 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?

Content is front-loaded: what is returned comes first, then usage ordering, exclusions, and caveats. It is dense but nearly every clause carries operational information; the index 'possible access paths, not observed query plans' clarification and the costSignal note are the most compressed items and border on terse.

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 schema-inspection tool with no output schema, the description covers return content, scoping limits, name resolution, absence semantics, and staleness handling. An agent has everything needed to invoke it correctly and interpret the result.

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 both parameters, giving a baseline of 3. The description adds real value on top by stating that short names match qualified names case-insensitively and by reinforcing scoping to only the needed tables, though it does not explain the maxAgeSeconds advisory behavior that the schema covers.

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

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

The opening sentence names a specific verb (Returns) and resource (schemas) and enumerates the exact content returned: column types/nullability, keys, foreign keys, indexes, DynamoDB keys/billing mode, and MongoDB estimated counts. It also explicitly separates itself from the inventory sibling, so an agent can distinguish the two 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?

It gives explicit ordering ('Call after get_infra_overview before writing queries'), an efficiency constraint ('request only needed tables'), and a hard exclusion with the alternative named ('Do NOT use for inventory; use get_infra_overview'). It also flags a caveat on interpretation ('Read source health before treating found:false as absence').

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=true, openWorldHint=false), so the bar is lower, and the description adds genuinely non-obvious behavior: filter policies determine required message attributes and violating publishers get messages 'silently dropped.' That is real operational consequence beyond the structured fields. It does not discuss data freshness, though the maxAgeSeconds schema entry covers that.

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, zero filler, with the return contents front-loaded and the call-to-action last. Every sentence carries distinct information.

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

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

With no output schema, the description usefully enumerates what comes back (subscription counts, encryption status, filter policies) and flags the silent-drop consequence. The one gap is the Kafka scope implied by the title but absent from the description.

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

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

Schema description coverage is 100% and maxAgeSeconds is documented in exhaustive detail (advisory semantics, dataHealth.withinRequestedAge, when to pass small vs. omit). The description adds nothing about parameters, 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?

States a specific verb (Returns) and resource (SNS topics) and enumerates what is included: subscription count, encryption status, and filter policies. It implicitly separates itself from siblings like get_queue_details and get_eventbridge_details by resource, but never names them, and the title's promise of 'Kafka topic details' is not reflected in the description text.

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

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

Gives explicit triggers: 'Call this before writing any SNS publish code or when reviewing event fan-out patterns.' That is actionable context for the agent. It stops short of a 5 because it names no alternative tool or when-not-to-call condition.

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 openWorldHint=false, and the description is consistent with that (it only generates SQL text). It adds real context beyond the annotations: the output includes a composite variant plus EXPLAIN verification guidance, and it explicitly disclaims existence checking.

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 short sentences, front-loaded with what is produced, then when to call it, then the caveat. No filler or restatement of the title.

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 describing the deliverable (ALTER TABLE statement, composite variant, EXPLAIN guidance), which is exactly what an agent needs to know before invoking it. Nothing material is missing for a two-parameter read-only generator.

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

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

Schema coverage is 100% with two well-described required parameters (table, column), so the schema already carries the parameter semantics. The description's phrase 'for a MySQL table column' merely restates that pairing and adds no format or constraint detail, making 3 the correct baseline.

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 artifact: generates the exact ALTER TABLE ADD INDEX SQL for a MySQL table column. The MySQL qualifier cleanly separates it from the sibling index tools (postgres_index_suggestions, suggest_mongo_index, suggest_gsi) without needing to open any schema.

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

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

Gives an explicit trigger: 'Call this when the analyzer flags a missing MySQL index or full table scan finding.' It also states one boundary condition (does not check for an existing index), but it never names an alternative tool for non-MySQL engines, leaving that routing to 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 only declare readOnlyHint=true and openWorldHint=false, and the description is consistent with them (it emits SQL rather than executing DDL). It adds genuinely useful behavior beyond the annotations: the output includes a partial index variant and a post-creation ANALYZE reminder, and it discloses the limitation that existing indexes are not checked.

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, all load-bearing: what is produced, when to call it, and the explicit non-guarantee. The output composition is front-loaded ahead of the usage guidance.

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

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

With no output schema, the description correctly fills that gap by enumerating what is returned (CREATE INDEX CONCURRENTLY SQL, partial variant, ANALYZE reminder). Combined with the existence-check caveat, an agent has enough to call and interpret results; only pagination/return-shape mechanics are absent and largely irrelevant for a two-string-input generator.

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 both params ('PostgreSQL table name', 'Column name to index'), so the schema already carries the parameter meaning. The description restates 'table column' without adding format, qualification, or naming-convention detail, 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 and artifact (generates the exact CREATE INDEX CONCURRENTLY SQL) for a specific resource (PostgreSQL table column), and names sibling-adjacent alternatives implicitly by being PostgreSQL-specific against suggest_gsi/suggest_mongo_index/mysql_index_suggestions. An agent can distinguish it from all listed siblings without opening a schema.

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

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

Gives two concrete invocation triggers ('when the analyzer flags a missing index finding' or 'when writing a query that filters on a column without an existing index') and one exclusion ('Does not verify whether the index already exists'). It stops short of explicitly naming sibling tools as alternatives, but the when-to-use conditions are 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 declare readOnlyHint=true, and the description is consistent — this only proposes a definition rather than mutating the table. It adds genuinely useful behavior beyond the annotations: it checks existing indexes first and returns alreadyIndexed: true with the existing index name instead of proposing a duplicate. It does not describe the non-duplicate return shape, which would have pushed this to 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?

Three sentences, each earning its place: capability, trigger conditions, and idempotent-check behavior. The capability is front-loaded and the alternative is routed at the end.

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 present, the description correctly compensates by describing the alreadyIndexed return and its semantics for a duplicate attribute. It covers the common case well, though the full output shape for the success path is only partially implied.

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 both parameters are documented in the schema, so the schema carries the load. The description implies the attribute is what gets keyed and the table is the target, but adds no syntax or format detail beyond the schema — baseline 3.

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

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

The description names a specific verb and resource — generates a ready-to-use DynamoDB GSI definition — and enumerates what the output contains (index name, partition key, projection type, billing mode). It clearly separates itself from sibling get_table_schema by naming it as the tool for the full index 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?

Explicit trigger conditions are given: when a query pattern needs an index that does not exist yet, or when the analyzer flags a missing GSI finding. It also names the alternative (get_table_schema) and the condition that selects it, 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=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: what the output contains (createIndex command, compound/text variants, verification explain query) and the limitation that it will not detect an existing index. It stops short of saying the output is advisory only or how duplicates would manifest.

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, each earning its place: output scope first, invocation triggers second, limitation last. 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?

No output schema exists, and the description compensates by describing what is produced and why (verification via explain). With annotations covering safety, triggers covered, and the duplicate-index caveat stated, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% with only two parameters (field, collection), both self-describing, so the schema carries the semantics. The description adds no format, naming, or dot-notation guidance for nested fields that would go 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 precise verb+resource ('Generates the exact db.collection.createIndex() command for a MongoDB field') and enumerates the deliverables (compound and text variants, explain query). This clearly separates it from the sibling index tools suggest_gsi, postgres_index_suggestions, and mysql_index_suggestions.

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 two concrete triggers ('when a collection scan is flagged by the analyzer' or 'when writing a query that filters on an unindexed field') and adds a boundary condition ('Does not check whether the index already exists'). The only minor gap is not naming a sibling as the alternative, but the invocation conditions are fully explicit.

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