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?

Annotations already declare destructiveHint=true and openWorldHint=true; the description adds useful details such as execution through --cli-input-json, session-based defaults, return of parsed JSON, and the literal command that was run. It does not warn about reviewing destructive operations, but that burden is partly covered by 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 information-dense with no filler: core action, naming conventions, parameter format, session behavior, exclusions, and output format are all covered. It is longer than some definitions, but the arbitrary AWS API surface justifies nearly every sentence.

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 low-level AWS call with no output schema, the description covers naming conventions, parameter serialization, session defaults, output handling, and when to use a different approach. It could mention pagination or error behavior, but these are partially handled by sibling tools and the general AWS CLI contract.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful conventions: kebab-case service/operation names, PascalCase API parameter keys, JSON object passing via --cli-input-json, and JMESPath query examples. This goes beyond the schema's individual parameter descriptions and helps an agent invoke correctly.

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 it runs arbitrary AWS API operations via the aws CLI with kebab-case service and operation names. It distinguishes itself from high-level wrappers by explicitly targeting the low-level API, making it easy for an agent to separate from sibling resource-specific 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?

Explicitly routes high-level wrappers like 'aws s3 cp' or 'aws ec2 wait' to the shell, and frames this tool as the low-level API option. It also clarifies that session profile/region from aws_session_set are used by default and can be overridden per call, giving clear context for when and how to invoke it.

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

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

Annotations 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 the tool readOnly/idempotent/non-destructive, and the description adds substantial behavioral context beyond them: the `unknown` fallback for malformed EvalDecision responses, pagination semantics (hasMore/marker with per-page summary scope), the opaque spawn-error failure mode for oversized batches, the server-side ['*'] default that this tool deliberately does not inject, and the iam:SimulatePrincipalPolicy authorization requirement. No contradiction with annotations — the simulation is genuinely read-only.

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

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

The core purpose is front-loaded in the first sentence, and every subsequent sentence earns its place: return semantics, malformed-response fallback, pagination caveat, pre-flight usage, and auth requirement are each stated once with zero redundancy. The length is proportionate to genuine complexity (8 parameters, pagination, edge cases).

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 fully carries the burden of explaining return values — one entry per (action, resource) pair, all four decision values, matchedStatementIds, missingContextValues, hasMore/marker, and per-page summary scoping — and also covers pagination, batch limits, the context-key feedback loop, and the caller permission prerequisite. Nothing an agent needs to call and interpret 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%, so baseline is 3. The description adds real value on top: it explains the actions×resources multiplication and the single-argv spawn-error ceiling for resources, the server-side ['*'] default when resources is omitted, and the missingContextValues feedback loop that tells you which contextEntries to supply. This is above baseline, though the schema already documents most parameters well on its own.

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 is precise: 'Simulate IAM permissions for a principal: can principal X do actions Y on resources Z?' — a specific verb, resource, and the exact question the tool answers. Naming the wrapped API (iam simulate-principal-policy) and the tool's role relative to execution tools like aws_call makes its purpose 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?

It states exactly when to invoke the tool — 'Use this BEFORE a risky operation to avoid a 403' — and describes the pairing with 'the post-failure Suggestion you get from aws_call,' giving clear usage context. It stops short of a 5 because it gives no explicit when-not-to-use guidance or exclusion scenarios, though no sibling tool is a true alternative for simulation.

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 this as non-read-only, destructive, open-world, and non-idempotent. The description adds important behavior beyond those annotations: only synchronous RequestResponse is supported, the returned logTail is the last ~4 KB of the function log already base64-decoded, and a non-empty functionError means the handler threw while the invocation itself still succeeded.

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

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

The description is front-loaded with the core purpose, then moves efficiently through the aws_call alternative, the logTail return behavior, and the important functionError caveat. Every sentence carries operational value and no sentence is redundant.

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

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

For a complex AWS invoke tool with seven parameters, no output schema, and destructive/open-world annotations, the description covers the return shape, logTail behavior, functionError semantics, supported invocation type, and relevant alternatives. It provides enough context for an agent to invoke and interpret the call correctly.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, including payload omission behavior, qualifier format, region/profile overrides, and timeout guidance. The description reinforces synchronous RequestResponse usage but does not add substantial parameter-level meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: synchronously invoke a Lambda function and return both the response payload and the decoded execution log tail. It explicitly distinguishes this tool from the sibling aws_call by explaining why aws_call cannot reach Lambda invokes, so an agent can select it 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 explicit when-to-use guidance: use this instead of aws_call for Lambda invokes, with the structural reason that aws lambda invoke requires a positional output file and rejects --cli-input-json. It also names the alternative for DryRun (aws_iam_simulate) and states that async Event and DryRun are deliberately not implemented.

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?

Annotations already cover the safety profile (readOnly, openWorld, non-destructive, non-idempotent), but the description adds genuinely non-obvious behavior: truncation drops the OLDEST events, sets truncated=true and reports totalEvents; the maxEvents cap bounds the RESPONSE while the CLI still drains the whole window server-side, with cost implications. This is exactly the kind of context 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 purpose, then returns, then truncation semantics, then cost guidance -- a logical order with no filler sentences. It is dense and somewhat repetitive with the schema on maxEvents/truncation, which keeps it short of a perfect score.

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 fully specifies the return shape (JSON, oldest-first, cap behavior, truncated flag, totalEvents count) and the non-streaming call pattern. Nothing an agent needs to invoke this correctly or interpret the result 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 every parameter including since, maxEvents, and logGroupName is already documented in-schema (the ARN acceptance, pattern format, mutual exclusivity of stream filters). The description's maxEvents/since explanation largely restates the schema text, so the baseline 3 is appropriate.

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

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

Specific verb+resource ('Tail CloudWatch Logs for a log group') with an explicit scope statement distinguishing it from the raw FilterLogEvents API and clarifying it mirrors the CLI's parsing/grouping. An agent can tell it apart from sibling aws_logs_query without opening either schema.

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

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

Gives clear operational context: 'Does NOT stream -- run once to fetch the window, then call again with a later since', and advises narrowing via filterPattern or smaller since on busy groups. It does not, however, explicitly name the alternative sibling (aws_logs_query) or state when to prefer it, so the routing guidance is implicit rather than complete.

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?

Goes well beyond the annotations by disclosing partial failure expectations, duplicate-region collapsing, a 5 MB result cap, truncation with status preservation, and the top-level truncatedRegions field. These are behavioral traits not encoded in readOnlyHint/destructiveHint and are exactly what an agent needs to interpret batch results correctly.

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?

Every sentence carries distinct information: purpose, shape comparison, return shape, failure semantics, duplicate handling, size cap, truncation remedy, and use cases. It is front-loaded with the core purpose and then layers edge-case behavior without redundancy.

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

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

For a complex multi-region tool with no output schema, the description covers the return format, per-region outcome fields, expected partial failures, truncation behavior, and recovery path. Combined with the fully documented input schema and annotations, there is no critical missing context for invoking 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, but the description adds meaningful semantics: region duplicates collapse with first occurrence winning, regionCount reports actual executions, and timeoutMs applies per region via the aws_call shape reference. It could have also explained concurrency/profile, but the schema already documents 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?

Description states a specific verb and resource: 'Run the same AWS API operation across multiple regions in parallel.' It differentiates from aws_call by explicitly contrasting 'regions: string[]' with 'region', and gives concrete example 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?

Provides clear usage context with 'Use for fleet-wide reads' and concrete examples (describe-instances, list buckets, IAM password policy), plus advice to re-run truncated regions individually or narrow with query/params. It does not explicitly state when not to use the tool (e.g., single-region calls should use aws_call), so it stops short of a 5.

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

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

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.