Server Quality Checklist

Tool Scores

• aws_resource_listA
  4/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• aws_logs_tailA
  4.1/5.0
  Behavior4/5

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

  Annotations already indicate read-only, non-destructive operation. The description adds behavioral context: it runs once (not streaming), wraps CLI for consistent time parsing, and advises optimization for long windows. 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.

  Conciseness5/5

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

  The description is only 5 sentences, front-loading the purpose, and each sentence adds value: core function, CLI wrapping, output format, non-streaming behavior, and optimization advice. No fluff.

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

  Completeness3/5

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

  Given no output schema, the description only vaguely mentions 'Returns recent events as JSON.' It lacks specifics about output structure, error handling, or API limits (e.g., CloudWatch Logs pagination). Adequate but could be more complete.

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

  Parameters3/5

  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 does not add new parameter-level information beyond what the schema already provides, but it reinforces the use of `filterPattern` and `since` for narrowing.

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

  Purpose5/5

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

  The description clearly states the tool tails CloudWatch Logs for a log group, wraps the 'aws logs tail' CLI, and returns recent events as JSON. It distinguishes itself from a streaming tail and from sibling tools by focusing on a single fetch operation.

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

  Usage Guidelines4/5

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

  The description provides explicit guidance on usage: run once to fetch the window, call again with a later `since` for continuous tailing, and narrow long windows via `filterPattern` or lower `since`. It lacks explicit when-not-to-use comparisons with siblings, but the context makes the use case clear.

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

• aws_resource_statusA
  4.2/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• aws_whoamiA
  4.2/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• aws_session_getA
  4.4/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• aws_docs_searchA
  4.5/5.0
  Behavior4/5

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

  Annotations already indicate readOnly, idempotent, and openWorld hints. The description adds behavioral details: it returns ranked results with specific fields (title, url, summary, excerpt) and uses the live backend, providing useful 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.

  Conciseness5/5

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

  Concise three sentences, front-loaded with the core action. Every sentence adds value: purpose, use cases, return format, and follow-up action.

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

  Completeness5/5

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

  No output schema, but description explains return format. Mentions follow-up with aws_docs_read, providing complete guidance for using the tool effectively.

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

  Parameters4/5

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

  Schema coverage is 100%, baseline 3. The description gives query examples and mentions limit implicitly, adding meaning beyond the schema descriptions.

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

  Purpose5/5

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

  The description clearly states it searches live AWS documentation using the same backend as docs.aws.amazon.com, providing specific use cases and distinguishing from sibling aws_docs_read by suggesting a follow-up action.

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

  Usage Guidelines4/5

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

  Explicitly describes when to use: to discover doc pages for services/APIs the model may not know, new services, changed APIs, exact parameter names. It also mentions the alternative aws_docs_read for full page retrieval, though it doesn't explicitly state when not to use.

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

• aws_resource_getA
  4.5/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• aws_session_clearA
  4.5/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• aws_session_setA
  4.5/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• aws_list_profilesA
  4.6/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• aws_login_startA
  4.6/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• aws_refresh_if_expiring_soonA
  4.6/5.0
  Behavior5/5

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

  The description discloses behavior beyond annotations: it can trigger aws_login_start, returns specific outputs (verification URL/code or status with minutes left), and mentions a default threshold of 10 minutes. Annotations only indicate non-readonly and non-destructive, so description adds significant value.

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

  Conciseness5/5

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

  Three sentences, each essential: purpose, conditional behavior, usage recommendation. No redundant information. Well-structured with clear cause-effect.

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

  Completeness4/5

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

  No output schema exists, but the description explains the two possible return states (verification URL+code or status+minutes left). It doesn't detail exact structure of the verification response, but that can be inferred from aws_login_start sibling tool. Overall sufficient given tool simplicity.

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

  Parameters4/5

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

  Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining the default thresholdMinutes (10) and the behavioral impact of crossing it, which the schema doesn't cover. This justifies a score above the baseline 3.

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

  Purpose5/5

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

  The description clearly states it's a proactive SSO token check, specifying two conditional behaviors: if expiring soon, it kicks off aws_login_start and returns verification URL/code; otherwise returns status 'ok'. This distinct verb+resource combination differentiates it from siblings like aws_login_start 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.

  Usage Guidelines4/5

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

  The description explicitly advises using it 'at the start of a multi-step AWS workflow to avoid mid-session expiry', providing clear context. However, it doesn't mention alternatives or when not to use it, slightly limiting guidance.

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

• aws_resource_createA
  4.6/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• aws_resource_deleteA
  4.6/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• aws_assume_roleA
  4.7/5.0
  Behavior5/5

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

  Annotations only indicate readOnlyHint=false and destructiveHint=false. Description adds critical behavioral info: raw credentials are NOT returned (only profile name, expiration, identity), side-effect of writing to ~/.aws/credentials, and timeout default vs. runAwsCall's – all beyond what annotations convey.

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

  Conciseness5/5

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

  Five focused sentences with zero wasted words. Front-loaded with core action and outcome. Every sentence provides unique context (side effects, return info, timeout guidance, use case).

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

  Completeness5/5

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

  No output schema exists, but description details what is returned (profile name, expiration, identity). Covers all 8 parameters through schema descriptions and additional behavioral notes. Addresses timeout customization, prerequisites (source profile), and integration with sibling tools.

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

  Parameters4/5

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

  Schema coverage is 100% with per-parameter descriptions. Description adds extra value: explains timeoutMs vs runAwsCall default, auto-prefixing of targetProfile, and expansion of default behaviors. This justifies above baseline 3.

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

  Purpose5/5

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

  Description specifies 'Call STS AssumeRole and stash the returned temporary credentials as a named profile' – a clear verb+resource+outcome. It distinguishes from sibling tools like aws_session_set by explaining that credentials are stored for reuse with aws_call/aws_whoami/aws_paginate, and frames it as 'cross-account access' use case.

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

  Usage Guidelines4/5

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

  Explicitly states use case: 'Use for cross-account access: a source profile assumes a role in another account.' Also gives guidance on timeout adjustments for slow setups. Could note when to prefer aws_session_set over this, but the provided context is sufficient for most agents.

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

• aws_docs_readA
  4.7/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• aws_metrics_queryA
  4.7/5.0
  Behavior5/5

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

  The description goes well beyond the annotations (readOnlyHint, idempotentHint) to explain key behaviors: auto-pick period logic, pagination via nextToken/hasMore, response structure, expression vs metric-stat distinction, and how malformed inputs cause downstream errors. This gives the agent a thorough understanding of 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.

  Conciseness4/5

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

  The description is fairly long but well-structured and front-loaded with the main purpose. Each part adds value, though there is slight repetition of period auto-pick details. Overall, it efficiently covers all needed aspects without unnecessary fluff.

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

  Completeness5/5

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

  Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains the response format (series with timestamps/values), pagination, period semantics, and error behavior. Without an output schema, it compensates by describing return fields. Only minor detail like error conditions for missing required fields is omitted, but schema covers that.

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

  Parameters5/5

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

  Schema description coverage is 100%, so baseline is 3, but the description adds substantial value beyond schema. It explains how to structure queries (flat array of objects), clarifies startTime/endTime shorthand ('15m', '1h'), details auto-pick period rules, describes maxDataPoints server-side behavior, and explains nextToken usage. This enriches parameter understanding significantly.

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

  Purpose5/5

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

  The description clearly states it queries CloudWatch metrics via GetMetricData, distinguishing it from the legacy get-metric-statistics API. It specifies the resource (CloudWatch metrics) and the action (query), and gives concrete examples like 'show me the CPU on this instance for the last hour'. This differentiates it from sibling tools that handle other AWS actions like aws_resource_list or aws_logs_tail.

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

  Usage Guidelines4/5

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

  The description provides clear guidance on when to use this tool, explicitly contrasting with the legacy API and giving example use cases. It does not explicitly state when not to use it, but the sibling tools cover different AWS operations, so context suffices. The examples (CPU, Lambda invocations, expressions) illustrate appropriate scenarios.

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

• aws_multi_regionA
  4.7/5.0
  Behavior5/5

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

  Beyond annotations (which show readOnlyHint=false, etc.), the description adds critical details: partial failure is expected, duplicate regions are collapsed, returns regionCount for actual count, per-region error isolation, and validation details. 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.

  Conciseness4/5

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

  The description is three sentences plus a list of examples. It front-loads the purpose and key behavior. While the examples are extensive and helpful, the description could be slightly more concise, but it remains well-structured and informative.

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

  Completeness5/5

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

  Given 9 parameters, no output schema, and complex parallel behavior, the description covers return shape, concurrency, timeout, duplicate handling, validation, and provides usage examples. It fully equips an agent to invoke the tool correctly.

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

  Parameters5/5

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

  Schema description coverage is 100%, and the description adds value by explaining the relationship to aws_call parameters (same shape), regions behavior (collapsing, validation), concurrency default, and timeout per region. The return structure is also described despite no output schema.

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

  Purpose5/5

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

  The description clearly states 'Run the same AWS API operation across multiple regions in parallel.' It distinguishes from sibling aws_call by specifying the difference (regions array vs single region) and gives concrete examples like 'describe-instances across all our regions'.

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

  Usage Guidelines4/5

  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 provides examples like 'list buckets in every region'. It implies when not to use (not for writes), but does not explicitly exclude alternative tools. However, the similarity to aws_call is noted, giving clear context.

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

• aws_resource_diffA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description adds that no mutation is sent, simulation is in-memory, and the supported subset (add/remove/replace). No contradictions. Adds 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.

  Conciseness5/5

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

  The description is concise: two main sentences covering purpose, usage, and limitations. No fluff. Front-loaded with core action. Every clause earns its place.

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

  Completeness5/5

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

  For a tool with 6 parameters (3 required), annotations, and no output schema, the description fully covers when to use, what it does, what it returns, and its limitations. It also references the sibling tool appropriately. Sufficient for correct invocation.

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

  Parameters4/5

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

  Schema coverage is 100% with descriptions on all parameters. Description enhances 'patchDocument' by explaining it supports only add/remove/replace and rejecting move/copy/test. This adds meaning beyond the schema's enum listing.

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

  Purpose5/5

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

  The description uses specific verb-resource phrases: 'Dry-run a CCAPI update', 'fetch current state', 'simulate applying a JSON Patch', 'return before/after plus changed paths'. It clearly distinguishes from the update tool by noting this is a preview.

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

  Usage Guidelines5/5

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

  Explicitly states 'Use this before aws_resource_update to verify the patch does what you expect.' Also indicates when to use the sibling directly: 'use aws_resource_update directly if you need move/copy/test'. Provides clear context and exclusions.

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

• aws_scriptA
  4.7/5.0
  Behavior5/5

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

  The description goes far beyond the annotations. It discloses timeout behavior, best-effort interruption, non-cancellation of in-flight aws.* calls, risk of double-mutation on retry, console.log capture, error throwing, and sandbox limitations. This rich behavioral context complements the destructiveHint annotation with concrete risk details.

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

  Conciseness5/5

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

  The description is long but every sentence adds value. It front-loads the purpose, provides a concrete example, then systematically covers execution semantics, helpers, sandbox restrictions, and timeout behavior. No filler; dense but well-organized.

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

  Completeness5/5

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

  For a tool that executes arbitrary code, this is remarkably complete. It explains return values, error handling, timeouts, retry risks, and runtime limitations. Since there is no output schema, it still clarifies what the agent will receive (combined result with console.log). It fully addresses the complexity of the tool.

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

  Parameters3/5

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

  Schema coverage is 100%: both parameters have detailed descriptions in the schema itself, so the description doesn't need to add param-specific semantics. The tool description repeats some of the code parameter behavior but doesn't add new parameter meaning beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

  Purpose5/5

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

  The description clearly states the tool runs a JavaScript snippet that orchestrates other aws-mcp tools and returns a combined result. It includes a concrete example and explicitly names the orchestratable tools, distinguishing it from sibling tools like aws_call and aws_paginate.

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

  Usage Guidelines5/5

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

  It explicitly says 'Best for batched read+filter+aggregate workflows that would otherwise need N tool round-trips' and provides an example. It also warns that it's not a security sandbox and lists which tools are intentionally not bound, directing the agent to call them as siblings instead. This gives clear when-to-use and when-not-to-use guidance.

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

• aws_callA
  4.8/5.0
  Behavior4/5

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

  Annotations only provide basic hints, but the description adds significant context: params go via --cli-input-json, returns parsed JSON and the raw command, timeout defaults to 60s, and query parameter reduces output. Could still mention error handling or permission requirements, but overall strong.

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

  Conciseness5/5

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

  The description is concise (4 sentences) and well-structured: main purpose first, then conventions, then usage boundaries, then output details. 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.

  Completeness5/5

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

  Given the tool's complexity (8 params, no output schema, many siblings), the description covers all essential aspects: what it does, how to call it, parameter formats, when to use vs alternatives, and return behavior. It is fully sufficient for correct agent invocation.

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

  Parameters5/5

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

  All 8 parameters have schema descriptions (100% coverage), and the description adds meaningful extra context: kebab-case naming, PascalCase keys for params, JMESPath usage for query, and advice to use query for smaller output. This goes well beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Run an arbitrary AWS API operation via the aws CLI.' It specifies the naming convention (kebab-case) and distinguishes from high-level wrappers, making its purpose unambiguous and distinct from siblings.

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

  Usage Guidelines5/5

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

  The description explicitly tells when to use this tool (for low-level API operations) and when not to (use shell for high-level wrappers like 'aws s3 cp'). It also mentions session defaults and per-call overrides, providing clear guidance.

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

• aws_login_completeA
  4.8/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• aws_paginateA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• aws_iam_simulateA
  5/5.0
  Behavior5/5

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

  The description adds significant behavioral context beyond annotations, explaining the return format (decision types including 'unknown' as a fallback), matched statements, and missing context values. It does not contradict annotations; instead it enriches understanding of 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.

  Conciseness5/5

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

  The description is concise, well-structured, and front-loaded. Every sentence provides critical information without redundancy. It efficiently covers purpose, usage, response details, and prerequisites.

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

  Completeness5/5

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

  Given the tool's complexity with 7 parameters and no output schema, the description provides complete context: usage guidance, permission requirements, response structure, edge cases (unknown decision), and parameter semantics. It fully equips 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.

  Parameters5/5

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

  The description adds meaning beyond the input schema, such as explaining that when resources are omitted, AWS defaults to ['*'] server-side and that this tool does not inject ['*']. It also clarifies the purpose of contextEntries and ties it to missingContextValues in the response.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Simulate IAM permissions for a principal: can principal X do actions Y on resources Z?' It uses a specific verb (simulate) and resource (IAM permissions), and distinguishes from sibling tools like aws_call by focusing on pre-execution checking.

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

  Usage Guidelines5/5

  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 ('Use this BEFORE a risky operation to avoid a 403') and provides a sibling alternative ('pairs with the post-failure Suggestion you get from aws_call'). It also notes the required IAM permission, giving clear guidance.

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

• aws_resource_updateA
  5/5.0
  Behavior5/5

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

  Annotations show readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds behavioral context: async by default, returns a ProgressEvent with OperationStatus=IN_PROGRESS and requestToken, and details the polling mechanism. 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.

  Conciseness5/5

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

  The description is three sentences long, front-loaded with core purpose. Every sentence adds value: explains the tool, async behavior, and typical patch structure. No wasted words.

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

  Completeness5/5

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

  Given the complexity (10 parameters, async behavior, polling), the description is very complete. It explains default async, optional synchronous mode, patch format, polling parameters, and return value structure. No output schema, but the description sufficiently covers what an agent needs.

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

  Parameters5/5

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

  Schema coverage is 100% (all parameters described). The description adds significant meaning beyond schema: explains patchDocument with an example, explains awaitCompletion behavior and related parameters (pollIntervalMs, maxWaitMs, timeoutMs), and mentions ProgressEvent.RetryAfter overriding poll interval.

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

  Purpose5/5

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

  The description clearly states the tool updates an AWS resource via Cloud Control API using RFC 6902 JSON Patch. It distinguishes from sibling tools like aws_resource_create, aws_resource_delete, aws_resource_get, aws_resource_list, and aws_resource_status. The verb 'Update' and resource 'AWS resource' are specific.

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

  Usage Guidelines5/5

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

  The description explains that the tool is async by default, requiring polling via aws_resource_status, and that passing awaitCompletion: true makes it synchronous. It also provides a typical patch example, guiding when to use 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.