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

The description discloses important side effects beyond the annotations: credentials are written to a named profile in the shared credentials file, the resolved file path is returned, raw secrets are intentionally not returned, and there is a 120s default timeout with guidance for slow setups. This meaningfully extends 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 description is dense but well-organized, with the core operation first, followed by downstream usage, security-relevant behavior, use case, and timeout guidance. Every sentence contributes distinct information and none merely repeats the tool name or annotation 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?

Despite having 8 parameters and no output schema, the description provides enough context for an agent to call the tool correctly: what it does, where it writes, what is returned, how to use the resulting profile, when to use it, and how to adapt timeout. The schema covers parameter formats, so no critical operational detail is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real value by explaining the targetProfile naming convention ('mcp-<sessionName>', auto-prefix behavior, overrides), how sourceProfile relates to the SSO identity, and the rationale for timeoutMs being higher than runAwsCall's default. It does not add much for region, externalId, or durationSeconds, but the schema already covers those.

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 precise action and resource: 'Call STS AssumeRole and stash the returned temporary credentials as a named profile in the shared credentials file.' This clearly distinguishes aws_assume_role from sibling tools like aws_call or aws_session_set, and the annotation title reinforces the same purpose.

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

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

The description explicitly states when this tool is appropriate: 'Use for cross-account access: a source profile (your SSO identity) assumes a role in another account.' It also explains how resulting profiles are consumed by sibling tools, but it does not mention when not to use it or name alternative tools for same-account scenarios.

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

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

The description reveals important behavioral traits not visible in annotations: blob-typed params are base64-encoded, the CLI runs with --cli-binary-format base64 regardless of config, session profile/region defaults apply, and the return value includes both parsed JSON and the literal CLI command. It also discloses which operations stream output and therefore cannot run here. This is substantive context beyond the readOnly/destructive hints.

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

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

The description is long but every sentence adds necessary information for a tool this broad. It front-loads the core invocation pattern, then covers exclusions, waiters, binary handling, and output behavior without repetition or filler. The density is justified by the tool's complexity.

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

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

For an arbitrary AWS API caller with no output schema, the description covers invocation syntax, parameter casing, binary handling, streaming limitations, alternatives, default session behavior, waiters, timeouts, and return format. An agent has everything needed to call this tool correctly and to decide when to route to a sibling tool instead.

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?

Although the schema already describes all 8 parameters, the description adds critical semantic nuance: kebab-case for service/operation names, PascalCase for API params, JMESPath usage for query, and base64 handling for blob-typed members. This goes far beyond the schema's one-line descriptions and materially helps the agent construct correct calls.

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

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

The description opens with a specific verb+resource statement: 'Run an arbitrary AWS API operation via the aws CLI.' It immediately clarifies the tool's role as a general-purpose API caller and further distinguishes it from sibling tools by explicitly listing operations it cannot handle (e.g., s3api get-object, lambda invoke) and the alternatives to use instead.

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 guidance is explicit: it names operations that do not accept --cli-input-json, points to aws_lambda_invoke, aws_logs_tail, bedrock-runtime converse, or the shell as alternatives, and confirms that waiters work via 'wait instance-running'. This gives an agent clear when-to-use and when-not-to-use rules that go well beyond generic advice.

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 indicate readOnly, non-destructive, idempotent. The description adds that it strips nav/cookie-banner/feedback chrome, paginates with startIndex/maxLength, and the response includes hasMore/nextStartIndex. No contradiction with 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 with pagination details. Front-loaded with main functionality. Every sentence is informative and necessary.

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

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

For a read tool with 3 params and no output schema, the description explains pagination flow, default values, and chrome stripping. It is fully complete for effective use.

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%. Description adds context for the URL parameter (must be AWS docs page, from search) and explains pagination parameters (defaults, meaning of startIndex/maxLength). Adds value beyond schema descriptions.

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

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

The description clearly states 'Fetch an AWS documentation page and return it as markdown.' It specifies the required URL format and mentions it complements aws_docs_search, distinguishing it from sibling tools.

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

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

The description explains that the URL must be an AWS docs page, typically from aws_docs_search, and provides pagination details. It implicitly tells when to use this tool (after search) but doesn't explicitly state when not to use it, though context is sufficient.

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

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

Beyond the read-only/idempotent annotations, the description discloses the backend's fuzzy-match flaw (always returns confident-looking hits even for nonsense queries), the locally computed lexicalMatch metric, and the lowRelevance flag semantics. It warns the agent to re-query rather than citing weak hits, which is critical behavioral context. No contradiction with 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 description is long but every clause carries necessary caveats for a search tool with misleading backend behavior. It front-loads the main purpose and then layers the caveat and its interpretation; a minor redundancy in explaining 'no good match' slightly reduces conciseness.

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

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

No output schema exists, so the description carries the burden of explaining return shape and it does: ranked {title, url, summary, excerpt}, plus lexicalMatch and lowRelevance fields with exact meaning. It also gives a concrete follow-up action and enough caveat detail to prevent misuse.

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

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

Input schema already covers both parameters with descriptions and examples, so baseline is 3. The description adds the notion of query terms being used for lexical overlap, but it does not need to explain limit, which the schema documents fully.

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

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

Description opens with a specific verb-resource pair ('Search the live AWS documentation') and explicitly states the use case: 'discover the right doc page for a service, API, or concept the model may not know about'. It distinguishes itself from the sibling aws_docs_read by framing search as the discovery step and read as the follow-up.

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 conditions for use: discovering new services, recently changed APIs, and exact parameter names. It identifies the logical next tool (aws_docs_read) but does not explicitly state when not to use this tool, stopping short of a full when/when-not contrast.

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 mark readOnlyHint and idempotentHint, but the description goes far beyond them: it details the exact return fields (decision, matchedStatementIds, missingContextValues, permissionsBoundaryDecision, organizationsDecision), the unknown fallback, the behavior of SCP statements, the fact that 'allowed' is not sufficient, and the authorization requirement (iam:SimulatePrincipalPolicy). No contradiction with 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 description is long but dense. It is front-loaded with the core purpose, then moves to output shape, limitations, usage guidance, and permission requirements. Every sentence adds unique information; no filler. The structure (purpose → return → caveats → usage → auth) makes it easy for an agent to extract the key facts quickly.

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?

This is a complex tool with no output schema, so the description must carry the full burden of explaining return values, and it does: it names every field and their meaning. It covers pagination, the fallback behavior, the limitations of what is evaluated, and the caller's required permission. An agent has everything needed to call it correctly and interpret results.

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

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

Schema coverage is 100%, but the description adds meaning beyond each field's schema definition: for resources it explains the server-side default and the batch-size limit; for principalArn it clarifies why the STS session ARN from aws_whoami won't work and how to get the correct role ARN; for marker it explains the pagination interaction; for contextEntries it links them to missingContextValues. This is substantial added value.

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 ('Simulate IAM permissions'), a resource (principal, actions, resources), and the wrapped CLI command. The core question 'can principal X do actions Y on resources Z?' gives immediate clarity. It is clearly distinct from siblings like aws_resource_list or aws_call.

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

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

Explicitly says when to use: 'Use this BEFORE a risky operation to avoid a 403'. It also names a companion tool (aws_call) and explains how it pairs. The limitations section (RCPs, session policies not evaluated) implicitly tells the agent when NOT to trust the result, serving as an exclusion. No other sibling is a direct alternative, so this is complete 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 only carry hint flags (destructiveHint=true, idempotentHint=false), so the description carries the burden — and it is exceptional. It discloses that the CLI's automatic retries are disabled ('The invoke is sent AT MOST ONCE'), that a non-empty functionError still means ok is true, and the dangerous middle case where 'the function may have run and may still be running — check its logs before invoking again.' This is exactly the information an agent needs to avoid double-invoking a non-idempotent function.

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?

Dense, front-loaded guidance: the core behavior and aws_call substitution come in the first two sentences. Each subsequent sentence earns its place by covering retry safety or error semantics, though there is minor redundancy with the timeoutMs parameter description's cold-start discussion.

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 must explain return semantics — and it does, covering logTail (last ~4 KB, base64-decoded), functionError (handler threw, ok still true, error in payload), and the three distinct failure classes with retry guidance. For a complex, non-idempotent invocation tool, nothing an agent needs to invoke correctly and avoid duplicate runs is missing.

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

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

Schema description coverage is 100%, and parameter descriptions are already rich (payload encoding, qualifier defaults, timeout cap at 900000 ms, invocationType rationale), so the baseline 3 applies. The main description adds tool-level semantics (logTail, functionError, retry safety) rather than per-parameter detail, which is the correct division of labor.

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: 'Invoke a Lambda function synchronously (RequestResponse)' and adds a differentiating outcome — 'return its response payload plus the DECODED tail of its execution log in one call.' It names the sibling it replaces ('Use this instead of aws_call') and the one for the Managed-Instances edge case (aws_logs_tail), so an agent can pick this tool 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?

Explicitly routes around aws_call ('Use this instead of aws_call for Lambda invokes') and explains why: 'aws lambda invoke needs a positional output file and rejects --cli-input-json, so aws_call structurally cannot reach it.' It also directs Managed-Instances users to aws_logs_tail and, for pre-flight permission checks, to aws_iam_simulate.

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, destructiveHint false, and idempotentHint true. The description adds value by revealing the specific file source (~/.aws/config) and the exact return structure, going beyond what annotations provide. No contradictions.

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 concise sentences front-load core information (what it does, what it returns) followed by usage guidance. No redundancy or unnecessary details.

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

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

For a tool with no parameters and no output schema, the description adequately covers purpose, return values, and usage context. Minor omission: potential error cases (e.g., missing config file) are not mentioned, but overall it's sufficient.

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

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

The input schema has zero parameters with 100% coverage, so baseline is 4. The description doesn't need to explain parameters and instead focuses on return values, which is appropriate.

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

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

The description clearly states it lists AWS profiles from ~/.aws/config and specifies the returned fields (profile name, region, SSO metadata, isSso flag). It distinguishes itself from sibling tools by focusing solely on profile enumeration, not assuming roles or making API calls.

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 explicitly defines three use cases: when the user hasn't named a profile, when they ask to switch profiles, or when an SSO-expired error mentions a profile you haven't seen. This provides clear guidance on when to invoke this tool versus alternatives.

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

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

The description adds valuable behavioral context beyond annotations: blocking wait, waiting for browser auth or subprocess error, returning identity or structured error. Annotations provide readOnlyHint=false, which is consistent.

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 no wasted words. Front-loaded with purpose and then details.

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

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

For a tool with few parameters and no output schema, the description covers blocking behavior, return values, and parameter defaults, making it complete for an agent to use correctly.

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

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

Schema coverage is 100%. The description explains sessionId as returned by aws_login_start, profile default behavior, and region purpose for identity check, adding meaningful context.

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

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

The description clearly states the tool blocks until SSO login finishes, distinguishing it from aws_login_start which initiates the process. It specifies the blocking behavior and return types.

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 it should be called after aws_login_start, but doesn't explicitly state when not to use it or mention alternatives like aws_whoami for checking identity without blocking.

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?

Discloses that no browser is spawned from this process, which is important for an agent assuming a browser can be opened. Explains the external user interaction required and the need for a second call to complete login. Annotations are consistent.

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 serving a distinct purpose: describing the action, the output, and the follow-up. No unnecessary words. Highly efficient.

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

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

Despite no output schema, the description explains the return includes a verification URL, short code, and sessionId (implied). It provides enough context for an agent to use the tool correctly. Differentiation from 24 sibling tools is clear. Minor gap: explicit return structure not stated.

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 a clear description of the 'profile' parameter, including default behavior. The tool description does not add extra parameter details beyond the schema, but the schema is sufficient, so baseline of 3 is appropriate.

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

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

The description clearly states it starts an AWS SSO login via device-code flow, specifying the verb 'Start', resource 'AWS SSO login', and method 'device-code flow'. It distinguishes from sibling tools like aws_login_complete and aws_session_set.

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 tells when to use this tool (to initiate SSO login), how to surface the verification URL and code to the user, and the next step: call aws_login_complete with the returned sessionId. Provides clear flow 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 cover safety (readOnly, non-destructive, openWorld, non-idempotent), but the description adds materially more: per-byte SCANNED billing, the fact that a timeout or cancellation NEVER stops the query and the queryId stays retrievable for 7 days, the ARN-to-name collapse that silently breaks cross-account queries, and how `truncated` relates to `statistics.recordsMatched`. That is exactly the kind of behavior annotations cannot express.

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

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

Front-loaded with the core one-call promise, then progressively discloses billing, error semantics, and alternatives. It is long and there is some overlap with the input schema's own descriptions, but nearly every sentence carries operational weight.

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

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

For an 11-parameter tool with no output schema, the description documents the return shape ({queryId, status, rows, rowCount, fields, statistics, truncated}), the flattened row format, and the failure mode (queryId handed back on timeout). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: it explains the time-vocabulary shared with aws_logs_tail/aws_metrics_query, the 90-day cap, and the account-discarding ARN behavior on logGroupNames. It slightly duplicates the schema text rather than adding new syntax detail, keeping it short of a 5.

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

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

States a specific verb and resource ('Run a CloudWatch Logs Insights query and wait for it to finish') and explicitly frames itself as a single-call replacement for the start/poll/interpret sequence done via aws_call. An agent can distinguish it from aws_logs_tail and aws_call 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 routing: use this instead of the three-step aws_call dance, use aws_logs_tail for plain 'show me recent log lines' with no aggregation, and use aws_call for OpenSearch SQL. It also warns to narrow the window and add a `filter` before widening scope.

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

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

The description goes well beyond the readOnly/destructive annotations, detailing oldest-first ordering, null-field retention, truncation semantics, CLI version differences, cross-account ARN handling, and non-streaming behavior. This is a comprehensive behavioral disclosure that an agent can act on confidently.

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

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

The description is dense but front-loaded with purpose and return format. Every sentence conveys a distinct, useful fact (behavior, CLI version nuance, ARN handling, truncation). It is long out of necessity, not verbosity; no superfluous wording.

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

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

For a tool with no output schema and significant complexity (CLI version differences, cross-account ARNs, truncation), the description thoroughly explains return shape, edge cases, and operational caveats. It leaves no essential gap for correct invocation.

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

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

Schema coverage is 100%, with highly detailed parameter descriptions already provided. The description adds extra semantic value by explaining ARN acceptance, CLI version caveats, the omission of eventId/ingestionTime, and pointing to aws_call for those fields—context not present in the schema alone.

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

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

The description opens with 'Fetch the newest CloudWatch Logs events for one log group', a specific verb and resource, and names the underlying API (FilterLogEvents). It also differentiates from siblings by noting omitted fields and directing eventId/ingestionTime needs to aws_call, making its scope unmistakable.

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 concrete usage guidance: states the tool does not stream, recommends narrowing 'since' or adding 'filterPattern' for wide windows, and explicitly routes eventId/ingestionTime requests to aws_call. However, it does not contrast with the related sibling aws_logs_query, so the when-to-use instruction is not fully exhaustive.

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

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

Beyond the readOnly/idempotent annotations, the description thoroughly discloses behavioral details: relative time parsing rules, rejection of offset-less date-times, automatic period selection, response shape, effective vs inherited periods, pagination via nextToken, and server-side period widening for maxDataPoints. This gives the agent an unusually complete model of how the tool behaves before calling it.

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

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

The description is long but densely packed with actionable information and is well organized: API identity, query shape, time semantics, period auto-pick, response format, pagination, and example queries. Every sentence adds a behavioral or semantic detail that an agent needs, and the most important scoping information appears first.

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

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

Despite having no output schema, the description fully documents the return shape, including per-series period semantics, top-level periodSeconds, statusCode, and pagination fields. It also covers edge cases like date-only input, offset-less rejection, and maxDataPoints ceiling behavior. Given the tool's complexity, the description is complete enough for correct invocation.

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

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

Even though schema coverage is 100%, the description adds significant semantic value beyond the schema: exact period auto-pick thresholds, detailed startTime/endTime format rules, mutual exclusivity between expression and namespace/metricName, and the counterintuitive maxDataPoints behavior where CloudWatch coarsens the period rather than truncating points. This is rich, non-redundant parameter guidance.

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

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

The description opens with a specific verb and resource: 'Query CloudWatch metrics via GetMetricData'. It also distinguishes this from the legacy get-metric-statistics API and gives concrete example use cases ('show me the CPU on this instance', 'sum lambda invocations across these 3 functions'). This makes the tool's purpose unmistakable and differentiates it from any alternative.

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

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

The description explicitly states when to use the tool: for single-metric queries, multi-metric queries, and expression-based metric math. It explicitly contrasts with the legacy get-metric-statistics API, and the 'Use for' examples give an agent direct pattern-matching guidance. No other sibling tool handles CloudWatch metrics, so the usage boundary is clear.

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

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

Annotations only cover the read/write safety profile; the description adds substantial behavior beyond that: sessions held in memory and NEVER written to ~/.aws/credentials, partial failure is expected and normal, duplicate IDs collapse on first occurrence, and a 5 MB result cap that drops `data` and sets `truncated: true`. None of this contradicts the annotations (destructive/openWorld is consistent with running arbitrary operations).

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?

Dense but front-loaded: purpose first, then fan-out semantics, alternatives, return shape, then edge cases. It is a long single paragraph and every sentence carries information, though the return-shape and truncation detail could be trimmed if an output schema existed.

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 12-parameter, nested, no-output-schema tool, the description supplies the missing output contract in prose ({accountId, ok, data?, command?, error?, errorKind?}), plus partial-failure and truncation semantics. An agent has everything needed to call and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it frames the parameter set as 'same shape as aws_call', explains that duplicate account IDs collapse, points to the returned accountCount, and describes where roleName lands (per-account ARN, session name in CloudTrail). Slightly above 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?

Opens with a specific verb+resource+scope: 'Run the same AWS API operation across multiple ACCOUNTS in parallel by assuming the same role name in each.' It explicitly positions itself against siblings (aws_call shape, aws_assume_role in a loop, aws_multi_region is implied by naming accounts vs regions), so an agent can distinguish it 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?

Gives explicit when-to-use and when-not: it names two alternatives (Config aggregator, Resource Explorer) as lower-effort for indexed inventory questions, and states the condition that selects this tool ('arbitrary API operation across accounts with no setup'). This is about as clear as routing guidance gets.

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 carry only broad hints, while the description discloses important behaviors: partial failure is expected, duplicate regions are collapsed, results are capped at 5 MB with truncated data flagged, and truncation recovery is described. It also explains per-region error isolation and the result/error shape. No contradiction with 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 description is dense but every sentence earns its place. It front-loads the core behavior, then covers result shape, failure modes, truncation, duplicate handling, and usage examples in a logical flow. The length is justified by the tool's complex behavior and remains well-organized.

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

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

There is no output schema, yet the description fully specifies the return shape: array of {region, ok, data?, command?, error?, errorKind?}, plus regionCount, truncated, and truncatedRegions. It also covers concurrency limits, per-region timeouts, partial failure, and re-running strategies. An agent has everything needed to invoke and interpret the 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%, so the schema already documents every parameter. The description adds semantics that the schema cannot: regions max 64, at most 32 in flight, duplicate collapse with first-wins, and how query/params can narrow truncated results. This is meaningful added value beyond the schema.

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

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

The opening sentence states a specific verb and resource: run an AWS API operation across multiple regions in parallel. It immediately contrasts with aws_call by noting the regions parameter difference, and the examples (describe-instances, list buckets) clarify the intended use. This is fully distinguishable from siblings like aws_multi_account.

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 explicitly says 'Use for fleet-wide reads' and gives concrete examples, which makes the primary when-to-use case clear. It also references aws_call as the single-region counterpart, though it stops short of explicitly stating 'do not use this for single-region calls.'

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

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

The description explains the query wrapping mechanism, the return fields (parsed response, nextToken, hasMore), and pagination continuation. Annotations already declare readOnly=true, but the description adds valuable behavioral context beyond 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?

The description is a single focused paragraph, front-loading the purpose, then detailing mechanics and usage. Every sentence adds value 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?

The description covers the essential behavioral aspects and pagination loop. Without an output schema, it explicitly mentions return fields. It lacks mention of error handling or edge cases, but overall it is sufficiently complete for an experienced AWS user.

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 description enriches parameters by explaining defaults (maxItems=100), the effect of query wrapping, and the role of startingToken. It also clarifies how params are passed via --cli-input-json.

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

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

The description clearly states it fetches one page of a paginated AWS list/describe operation and distinguishes from aws_call by adding maxItems and startingToken. It identifies specific usage scenarios like avoiding the 5 MB cap.

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 explicitly says to use this instead of aws_call for operations that might exceed the 5 MB cap, listing examples. It implies aws_call for non-paginated operations, providing clear when-to-use 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?

The description goes well beyond the annotations by disclosing that status: 'ok' is a point-in-time reading, not a lease, and that no re-check happens afterwards. It also clearly states the side effect of triggering aws_login_start and returning a verification URL and code, which is essential for understanding the tool's behavior.

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

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

The description is moderately sized but every sentence earns its place: it states the core behavior, the conditional outcome, the recommended use case, and a crucial caveat. It is front-loaded with the main purpose and avoids unnecessary filler.

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

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

Given there is no output schema, the description does a good job covering return values (verification URL + code, or status: 'ok' with minutes left) and failure implications. It could have benefited from explicitly stating that the returned verification URL requires user interaction to complete login, but overall it is complete enough for safe invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful extra semantics for thresholdMinutes by explaining how to set it relative to workflow length and warning that 'ok' is not a guarantee. This is valuable beyond the basic schema definitions.

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

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

The description clearly identifies a proactive SSO token check with conditional refresh behavior, and names the resource (cached token) and side effect (kicks off aws_login_start). It doesn't explicitly name a sibling alternative it should be distinguished from, but the mechanism is clear enough that an agent can tell it apart from direct login or identity-check tools.

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

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

The description gives explicit when-to-use guidance: 'Use at the start of a multi-step AWS workflow to avoid mid-session expiry.' It also explains how to adjust thresholdMinutes to cover workflow length. It doesn't explicitly list alternatives not to use, but the context strongly implies this is a preliminary check before other AWS calls.

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

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

Annotations provide readOnlyHint false, destructiveHint false, etc. The description adds critical behavioral context: async by default, returns ProgressEvent with operation status, need to poll or use awaitCompletion. This goes beyond annotations and clarifies the full lifecycle.

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

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

The description is concise (3 sentences), front-loaded with the main purpose, and every sentence provides essential information. No unnecessary words, well-structured for quick reading.

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

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

Given 9 parameters and no output schema, the description explains the return format (ProgressEvent), token usage, and polling mechanics. It covers async/sync options and timeout parameters. Lacks mention of error handling or failure modes, but overall provides sufficient context for correct invocation.

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

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

Schema coverage is 100% with good descriptions. The description adds context for key parameters like desiredState (matching CFN schema), async polling parameters (awaitCompletion, pollIntervalMs, maxWaitMs), and explains their interaction. This adds value beyond the schema.

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

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

The description clearly identifies the tool's purpose: creating an AWS resource via Cloud Control API. It includes specific verb ('Create') and resource ('AWS resource'), and distinguishes from siblings by mentioning the async nature and Cloud Control API approach. Examples and async details further clarify.

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

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

The description explains when to use the tool (to create a resource) and provides guidance on the async vs sync behavior via awaitCompletion. It does not explicitly state when not to use it or compare to siblings, but the async pattern is well-explained, making the usage clear for most cases.

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

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

The description discloses the async behavior, the default IN_PROGRESS status, the awaitCompletion option, and the destructive nature. It aligns with annotations (destructiveHint true). It adds significant context beyond annotations, such as the polling parameters and warning to double-check identifier.

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

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

The description is composed of three concise sentences, each serving a distinct purpose: stating the function, explaining the async behavior and key parameters, and providing a safety warning. No extraneous information.

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

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

The description covers the core workflow (async vs sync) and warns about destruction. Given the complexity (9 params, no output schema), it adequately describes the return format (ProgressEvent) and polling mechanism. Missing details about error handling or ProgressEvent fields are mitigated by the schema and industry knowledge.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how parameters like awaitCompletion, pollIntervalMs, and maxWaitMs interact, and reinforces the idempotency token role. This improves the agent's understanding of parameter usage.

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

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

The description clearly states the verb 'Delete', the resource type 'AWS resource via Cloud Control API', and distinguishes it from sibling tools like aws_resource_create, aws_resource_update, etc. It is specific and unambiguous.

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

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

The description explains the async default and how to use awaitCompletion for synchronous polling, and mentions the alternative polling via aws_resource_status. It warns about destructive nature. However, it does not explicitly state when not to use this tool or provide alternatives for complex scenarios.

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

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

The description adds substantial behavioral context beyond the annotations: 'No mutation is sent to AWS', simulation happens in memory, moved/copy/test operations are rejected at schema validation, and CCAPI accepts those operations but the tool simply doesn't simulate them locally. This goes well beyond the readOnlyHint/idempotentHint annotations and clearly sets expectations for side effects and limitations.

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

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

The description is information-dense but every sentence earns its place: core purpose, safety guarantee, usage guidance, and operation-subset limitations are all covered in four sentences. The most critical fact ('No mutation is sent to AWS') is front-loaded early, and the alternative tool is named rather than implied.

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

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

Despite no output schema, the description tells the agent what to expect from the call ('before/after plus a flat list of changed paths'). It covers the tool's purpose, side-effect safety, input constraints, and the fallback path for unsupported operations. For a tool of this complexity, nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining the patchDocument subset semantics, clarifying that add/replace need a value, and explicitly routing move/copy/test away from this tool. This is more than redundant parameter restatement, but not a full re-documentation of each parameter.

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

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

The description states a clear verb and resource: 'Dry-run a CCAPI update', with explicit mechanics ('fetch the current resource state, simulate applying a JSON Patch in memory, and return before/after plus a flat list of changed paths'). It also distinguishes itself from aws_resource_update by emphasizing no mutation is sent to AWS, so an agent can immediately tell this tool apart from its 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?

The description explicitly says 'Use this before aws_resource_update to verify the patch does what you expect' and provides a clear exclusion: 'move'/'copy'/'test' operations should use aws_resource_update directly. This gives the agent explicit when-to-use and when-not-to-use guidance with named alternatives.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description adds that it returns parsed Properties and clarifies identifier formats, adding value beyond 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?

Three sentences, front-loaded with purpose, then format and usage guidance. No wasted words.

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

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

Covers all parameters and return type, with proper use cases. Lacks mention of error handling or permissions, but given simplicity of a read operation, it is largely complete.

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

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

Schema coverage is 100%, but description adds meaningful context: typeName format with example, identifier examples (function name, bucket name, etc.), and timeout default. This exceeds the 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?

Description clearly states 'Read a single AWS resource via Cloud Control API' and specifies it covers hundreds of resource types. It distinguishes from sibling aws_call by noting when to use that alternative.

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

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

Explicitly contrasts with aws_call for non-CCAPI or data-plane operations. Could mention other siblings like aws_resource_list, but the guidance is clear for its primary use case.

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, idempotentHint; description adds pagination details, return shape, and parent identifier context without contradicting 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 concise sentences, front-loaded with main purpose, no extra words.

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

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

Explains pagination and return fields despite no output schema. Adequate for a list tool with good annotations.

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 covers 100% of parameters. Description adds example for resourceModel but doesn't significantly augment beyond schema.

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

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

Clear verb 'List', specific resource 'resources of a given type', and distinct from sibling create/get/update/delete tools.

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

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

Mentions when to use resourceModel for nested types, but does not explicitly state when not to use this tool (e.g., for single resource retrieval use aws_resource_get).

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 and idempotent. Description adds the possible OperationStatus values and that it returns a ProgressEvent. No note on polling frequency or eventual consistency, but sufficient.

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 concise sentences with no unnecessary words. Front-loaded with 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?

Returns ProgressEvent and lists statuses. No output schema, but description covers the main return. Could mention that multiple calls may be needed, but still complete for a polling 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 covers all 4 parameters (100% coverage). Description only elaborates on requestToken, not on profile, region, or timeoutMs. At baseline level.

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?

Clearly states the tool polls status of async Cloud Control API requests (create/update/delete) using a requestToken. Differentiates from sibling tools that perform the actual operations.

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

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

Explicitly says to pass requestToken from create/update/delete tools. Implicitly it is for polling after those calls, but does not state when not to use (e.g., synchronous operations) or list alternatives.

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

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

The description clearly discloses the async behavior, the initial return shape (ProgressEvent with OperationStatus=IN_PROGRESS and requestToken), and the awaitCompletion polling option. Annotations already mark this as destructive and non-read-only, so the description adds useful behavioral context beyond those hints by explaining the asynchronous execution model and response semantics.

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

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

The description is three sentences with no filler. It front-loads the core action, then explains the async return behavior, then provides a clarifying example. 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?

Given 10 parameters, 100% schema coverage, and no output schema, the description covers the most important behavioral context: async request/response flow, the requestToken, how to opt into waiting, and a representative patch. It does not enumerate all parameters, but the schema already does that, and the sibling aws_resource_status is referenced in the schema for polling. The description is sufficiently complete for an agent to select and invoke the 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%, so the baseline is 3. The description adds value by showing a concrete RFC 6902 patch example with op, path, and value, and by explaining the meaning of awaitCompletion and the default async behavior. This goes beyond the schema's structural descriptions and helps the agent construct valid patchDocument payloads.

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

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

The description opens with a specific verb and resource: 'Update an AWS resource via Cloud Control API using RFC 6902 JSON Patch.' It clearly identifies the mechanism (Cloud Control API, JSON Patch) and distinguishes this from sibling tools like aws_resource_create, aws_resource_delete, and aws_resource_status by focusing on update semantics and async behavior.

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

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

The description gives concrete guidance on the two usage modes: async by default with immediate IN_PROGRESS response, or pass awaitCompletion: true to have the server poll until terminal. It also gives a typical patch example, helping the agent understand how to structure calls. It does not explicitly state when to prefer this over aws_resource_create/delete/status, but the purpose is unambiguous and the sibling names make the distinction 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?

Goes far beyond the annotations: the 'NOT A SECURITY BOUNDARY' warning, full server-process authority, timeout semantics (fires on pre-await sync spin but not post-await sync loops), in-flight aws.* calls not cancelled on timeout, and the retry double-mutation hazard all add critical behavioral context for a tool flagged destructiveHint=true. The console.log capture and throw-on-failure conventions are also disclosed. Nothing contradicts annotations; the description enriches rather than repeats them.

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 main description is front-loaded: purpose first, then best-use case, then return convention, then security warnings — and every sentence in the main body earns its place for a tool that executes arbitrary code. However, there is visible duplication between the description and the code parameter's schema text (bound-globals list, return convention, security warning, throw-on-failure), which is defensible but not perfectly lean.

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 the most complex and dangerous tool in the set — arbitrary code execution, no output schema, sparse annotations — the description covers the security boundary, timeout failure modes, retry hazards, environment restrictions, and error handling. The only real gap is the exact shape of the 'combined result' return value, which matters because no output schema exists to document it.

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

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

Schema coverage is 100% with unusually rich parameter docs — the code param enumerates bound, shadowed, and unavailable globals, and timeoutMs explains default/max, firing guarantees, and hang risk. The top-level description adds supplementary semantics: the `return <value>` convention, console.log lines returned alongside, and try/catch for throwing helpers. The schema does the heavy lifting, but the description genuinely adds meaning above the 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 opens with a specific verb and resource — 'Run a short JavaScript snippet that orchestrates other aws-mcp tools' — and enumerates exactly which tools it orchestrates (aws.call, aws.paginate, aws.resource.*, aws.logsTail, etc.), which are the sibling tools. This clearly differentiates it: it is the orchestration/batching layer atop the individual AWS-bound tools, not another AWS operation an agent might confuse with a 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?

Gives an explicit when-to-use — 'batched read+filter+aggregate workflows that would otherwise need N tool round-trips' — with a concrete example ('list all Lambdas, fetch each one's config, return those with memory > 1024'). It also states an explicit exclusion: auth/session tools and aws_list_profiles are intentionally unbound and must be called as sibling MCP tools instead, leaving no routing ambiguity.

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 indicate idempotentHint=true and destructiveHint=false. The description adds that subsequent calls fall back to env vars/defaults, which is useful context. No contradiction.

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: first states core action, second explains argument usage. No filler, front-loaded with essential information.

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

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

For a simple tool with two boolean parameters and no output schema, the description covers purpose, usage, and parameter behavior completely. It explains the effect on subsequent calls, which is sufficient.

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

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

Schema covers both parameters with descriptions. The tool description adds extra value by explaining default behavior (clears both) and how to clear just one, beyond the schema's individual parameter descriptions.

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

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

The description clearly states the tool removes session-set profile and/or region overrides, restoring default behavior. It distinguishes from sibling tools like aws_session_set and aws_session_get.

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 tells when to use the tool ('go back to the default profile', 'unset the region', 'reset session'). Explains behavior with no args vs. specific flags. Does not mention when not to use it, but the context is clear.

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

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

Annotations already indicate read-only, non-destructive, idempotent. Description adds specific behavioral detail on value sources ('session', 'env', 'default') and use cases. No contradictions.

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 waste. First sentence states action and output details; second provides use context. Front-loaded with core purpose.

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

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

Given no output schema and zero parameters, description adequately explains what the tool does and its output. Could mention that no input is needed, but 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?

No parameters; schema coverage is 100%. Description provides no param info, but none needed. Baseline 4 for zero-param 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?

The description clearly states the tool shows the current session's default AWS profile and region, along with provenance information. It distinguishes from siblings like aws_session_set and aws_session_clear by focusing on display/diagnosis.

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 it is useful for confirming state before operations and debugging account mismatches. Does not list when not to use, but context implies it's the correct choice for inspection.

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 indicate idempotentHint=true, and description adds that it returns resulting session state and both params are optional, providing useful behavioral context beyond 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?

Three sentences with no redundancy, front-loaded with purpose, efficient and clear.

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

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

Covers purpose, usage, behavior, return value, and optionality of parameters. Complete for a simple configuration tool with no output 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?

Schema coverage is 100% with descriptions; description adds that parameters are optional and can be used individually, enhancing meaning.

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

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

The description clearly states it sets the default AWS profile and/or region for the session, distinguishing it from siblings like aws_session_clear and aws_session_get.

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 examples of when to use (e.g., 'switch to prod') and explains effect on subsequent tools. Lacks explicit 'do not use' scenarios but sufficient for context.

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

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

Annotations already indicate read-only, non-destructive, and idempotent behavior. Description adds context about returning SSO token status and a structured fix-it message on expiration, which goes beyond 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?

Three concise sentences, front-loaded with core purpose, followed by usage guidance and special return behavior. No unnecessary words.

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

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

Parameters are fully documented in schema; description explains outputs including identity details and SSO status with fix-it message. No output schema, but coverage is adequate for a read-only identity 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% with clear parameter descriptions. The tool description does not add extra parameter semantics beyond what the schema provides, meeting the baseline for high coverage.

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

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

The description clearly states the tool shows current AWS identity details (account, role ARN, user ID) and SSO token status/time remaining, distinguishing it from sibling tools like aws_session_get or aws_login_start.

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 advises using this tool first to verify authentication before other AWS operations, and mentions return of a fix-it message if SSO is expired. No explicit when-not guidance, but context is clear.

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