Opsphere — DevOps & SRE Intelligence

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

Annotations already declare readOnly/destructive=false, so safety needs no coverage; the description instead contributes real interpretive context — ageCategory thresholds and, importantly, that chronic (>24h) alerts are known ongoing issues rather than new incidents, which materially changes how an agent should report results. It does not cover limits, pagination, or auth requirements, hence not a 5.

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

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

Purpose is front-loaded correctly, but nearly half the text is output-formatting mandates ('ALWAYS start your response with _summaryNote verbatim', 'include _signatureAscii in a code block') that are instruction creep relative to selecting and invoking the tool, and several listed result fields are already covered by the output schema.

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

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

For a read-only, zero-required-parameter lister with an existing output schema, the description is close to complete: it defines sources, active states, age semantics, and presentation expectations. Gaps remain around result limits/windowing and how to choose between this and the dedicated Datadog/PagerDuty/Prometheus sibling tools.

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 only three params, so the baseline is 3. The description adds modest semantics for `source` (alert/warn vs triggered/acknowledged) but never mentions `withDowntimes` or `context_id`, leaving whatever nuance those need entirely to 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?

States a specific verb and resource ('List active alerts') and defines what 'active' means per source: Datadog monitors in alert/warn, PagerDuty incidents in triggered/acknowledged. It does not, however, distinguish itself from siblings like dd_monitors_lookup, pd_incidents_search, or prom_alerts, so an agent must infer the boundary.

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

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

Usage is implied through the source split (datadog vs pagerduty), but that split is already encoded in the schema enum, so the description adds little routing guidance. There is no explicit 'use this instead of X' or when-not guidance against the many sibling alert/incident tools in this namespace.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that a summary of counts by health state is included and that each resource carries syncStatus and healthStatus, but it says nothing about behavior for large applications, result limits, or ordering.

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 key scope statement and free of filler; the contrast with argocd_app_unhealthy and the filter mention each earn their place. Slightly longer than necessary given it partly restates return fields.

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?

A read-only tool with full schema coverage, annotations, and an output schema covering return shape — the description supplies the scope and the sibling distinction an agent needs to call it correctly. Only large-result behavior is left unaddressed, which is a minor gap.

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

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

Schema coverage is 100%, so all six parameters are already documented in structured fields. The description only restates the kind and namespace filters and omits name, profile, instance, and context_id; with the schema doing the heavy lifting, this is the expected baseline.

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

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

States a specific verb and resource (returns all Kubernetes resources managed by an ArgoCD application) and defines the scope precisely as healthy and degraded alike. It explicitly contrasts with the sibling argocd_app_unhealthy, so an agent can distinguish the two without opening a schema.

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

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

Names the alternative (argocd_app_unhealthy) and the condition that selects it — failing resources only versus the complete picture — and points to argocd_list_apps for the required name. It doesn't address when to prefer argocd_get_app or argocd_debug for app-level status, so routing is clear but not exhaustive.

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

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

Annotations already establish that this is a safe read-only, non-destructive operation. The description adds that results include status, health, message, and suggested next steps, but it does not disclose edge behavior such as missing applications, empty results, or authentication/context requirements beyond what the schema already documents.

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 two sentences, front-loaded with the core filtering behavior, and every phrase contributes useful information. There is no repetition or filler.

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

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

An output schema exists, so the description need not explain return values in depth, and annotations cover the safety profile. The schema also fully documents the application, profile, instance, and context parameters. The only minor gap is lack of explicit sibling routing guidance, but the definition is otherwise complete for a read-only diagnostic tool.

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

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

Schema description coverage is 100%, so all four parameters are already well documented in the input schema. The description adds no parameter-level meaning beyond what the schema provides, making the baseline 3 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: it returns resources that are not Healthy or not Synced in an ArgoCD Application. This clearly distinguishes it from the broader sibling argocd_app_resources by its unhealthy/un-synced filter without requiring schema inspection.

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 when this tool is useful by naming the unhealthy/un-synced condition, but it does not explicitly state when to choose it over argocd_app_resources, argocd_get_app, or argocd_debug. No exclusions or routing guidance are provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description goes beyond that by disclosing what the call actually does internally (lists applications) and what it returns (resolved profile/context/namespace, reachability status, app count), which is genuinely useful. It omits any note on cost of listing many apps, but that is minor.

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

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

Three short sentences, front-loaded with the core action and then the return payload. No filler, though the trailing "Useful for troubleshooting" is the weakest 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?

With an output schema present, detailed parameter descriptions, and read-only annotations, the description supplies what is needed to call the tool correctly. Only the sibling differentiation is missing, which is partially outside this tool's scope.

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

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

Schema description coverage is 100% and each of the three optional parameters has a detailed description, so the schema carries the parameter burden. The tool description adds no parameter-level meaning, which matches 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 names a specific verb and resource (tests connectivity to an ArgoCD instance via listing applications) and states the returned data. It is clear on its own, but it never references the sibling argocd_* tools (argocd_get_app, argocd_app_unhealthy, argocd_app_resources), so an agent must infer how it differs from them.

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?

"Useful for troubleshooting" implies the intended situation (diagnosing connectivity/config problems) but gives no explicit when-not or alternative routing among the many sibling argocd tools. Usage is only implied, not stated.

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 annotations already establish that this is a read-only, non-destructive, non-open-world operation. The description adds useful scope by listing the spec and status content returned, but it does not disclose any additional behavioral context such as authentication requirements or limitations beyond what the schema and annotations provide.

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 two tightly written sentences with the core purpose front-loaded. Every sentence contributes useful information, and there is no filler.

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

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

Given the read-only annotations, complete parameter descriptions, and the existence of an output schema, the description is largely complete for invocation. Its main missing piece is sibling differentiation, which would help an agent choose this tool over other ArgoCD detail tools.

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 all four parameters are already well documented in the input schema. The description only implies that a specific application name is required and adds no extra semantics beyond the schema, which matches the baseline for fully documented parameters.

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 uses a specific verb and resource: it returns the full ArgoCD Application CRD for a named app. It also names the main contents (spec and status fields), making the tool's purpose clear. However, it does not distinguish this tool from sibling ArgoCD tools such as argocd_app_resources or argocd_app_unhealthy.

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

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

The description implies usage by saying it returns a specific app's full CRD, but it gives no explicit guidance on when to use this tool versus alternatives. With several ArgoCD siblings available, the absence of routing guidance is a clear gap.

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?

Adds real context beyond the annotations: session-based auth ('Uses the logged-in AWS session permissions'), the result-location prerequisite, and a row cap. However, the annotations declare readOnlyHint=false while the description only says 'read-only SQL', and the description never explains the tool's own side effects — a query execution resource is created and results are written to S3, which is also implied by the outputLocation parameter. It also omits any cost/data-scanning caution, which matters for Athena billing. The tension is reconcilable (the read-only claim is scoped to the SQL statement types) but is never made explicit.

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?

Five short sentences, each carrying distinct information (purpose, routing, prerequisite, auth, statement whitelist, output cap), with the primary action front-loaded. Nothing is repeated from the title or schema verbatim except the row cap, which adds the behavioral 'caps returned rows' framing.

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 9-parameter tool with full schema coverage and an output schema, the description covers routing, prerequisites, auth, statement restrictions and output limits — enough to invoke correctly. The remaining gap is behavioral rather than structural: no mention that execution writes to S3 and that the readOnlyHint=false annotation exists for that reason, and no cost/scan-size guidance.

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 does add one genuinely useful semantic: the workGroup / outputLocation requirement ('Requires workGroup and/or outputLocation (s3://…)'), a one-of constraint the schema does not express, and it restates the row cap ('Caps returned rows'). The remaining seven parameters get no added meaning in the prose.

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 read-only SQL query in Amazon Athena') plus the underlying engine flow (StartQueryExecution → results). It explicitly declares the sibling it supersedes ('Prefer this over aws_cli_query for Athena/Glue analytics'), so an agent can route without opening either schema.

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

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

Names the alternative (aws_cli_query) and the condition selecting this tool (Athena/Glue analytics), plus a hard prerequisite ('Requires workGroup and/or outputLocation'). The allowed statement whitelist (SELECT/WITH/SHOW/DESCRIBE/EXPLAIN) tells the agent what will be rejected before it 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 already declare readOnly/destructive false, but the description adds real value by naming the AWS surfaces touched (bedrock-agent, lambda, iam, logs) so an agent can reason about permissions and blast radius, and by promising deterministic findings plus a resource graph. It does not disclose latency, cost, or what the output report contains beyond the enumeration.

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

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

Three short sentences: capability scope, read-only/service boundary and sibling routing, then an example for the required input. Front-loaded and 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?

With annotations, a full input schema, and an output schema, the description covers what the tool gathers and its read-only posture, which is enough to call it correctly. It leaves unstated how the log window (hours) and alias selection affect results, but those are adequately covered in the schema.

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

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

Schema coverage is 100%, so all seven parameters, defaults, and bounds are already documented in structured data; the description only adds the hint that agentId comes from the console or list-agents. Baseline 3 applies since the schema does the heavy lifting and the description adds no syntax or format detail.

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 (Diagnose) and resource (Amazon Bedrock Agent) and enumerates exactly what is inspected: status, alias, action groups, Lambdas, IAM role, knowledge bases, resource graph, deterministic findings. This lets an agent distinguish it from generic siblings like aws_cli_query or aws_lambda_agent_diagnose without opening the schema.

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

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

"Prefer over aws_cli_query for operational triage" gives an explicit alternative and the condition that selects this tool. It also hints at how to obtain the required agentId (console or list-agents). It stops short of stating when NOT to use it or how to choose against aws_lambda_agent_diagnose.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known; the description adds real, non-duplicated enforcement detail — the read-verb allowlist (describe/list/get/search/scan) and that secrets are blocked. It stops short of covering credential/profile requirements, region defaults, pagination, or what happens on a blocked command.

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 capability, then the constraint, then the alternatives, then examples — every sentence carries weight and there is no filler. It runs slightly dense as one paragraph, but 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?

With an output schema present, the description needn't explain return values, and it covers the gaps that matter: what is blocked, which sibling to prefer, and callable command examples. Remaining gaps (auth/profile behavior, region defaults, error semantics on blocked calls) are modest for a generic passthrough 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%, so baseline is 3. The description still adds meaning beyond the schema's free-form string by defining the acceptable value class (read-verb subcommands only) and showing that extra CLI flags like --region can be appended to the command string, which the schema does not state explicitly.

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

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

States a specific verb+resource (run read-only AWS CLI queries) and immediately names the distinguishing scope: a generic fallback for services without a dedicated tool. It lists covered services (Lambda, CloudFront, SQS, SNS, Route53) so an agent can tell it apart from the many aws_* siblings without opening a schema.

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

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

Explicitly routes the agent: use this for services lacking a dedicated tool, and prefer aws_athena_query / aws_s3_find / aws_dynamodb_* / aws_rds_data_query for those cases. This is the when-to-use plus named-alternatives pattern done properly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful non-schema context: a hard result cap ('Returns up to 200 events') and the fact that credentials come from an AWS profile. It does not mention pagination or how truncation should be handled, which is the remaining gap.

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

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

Four compact sentences with the purpose and time-window mechanics front-loaded and no filler. Minor redundancy: the default of 1 hour and the ISO 8601 format are both repeated from the schema.

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

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

An output schema exists, so return structure needn't be explained. With 8 parameters and one required, the description covers search semantics, authentication source, time-selection modes, and result volume. The only omissions are pagination/truncation handling and any note on the context_id/region interaction.

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

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

Schema description coverage is 100% and every parameter (hours, startTime/endTime, filterPattern, logGroupName, profile, region) is already documented with examples and the hours-vs-timestamps override. The description's worked example restates what the schema already conveys, so it adds only marginal meaning beyond the structured data.

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 ('Search CloudWatch Logs events') plus the scoping dimensions (time window, filter pattern). The AWS-specific naming distinguishes it cleanly from siblings such as dd_logs_search, sentry_logs_search, azure_log_analytics_query, and vercel_deployment_logs without requiring schema inspection.

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?

Implied usage is clear (search log events in a log group over a time window), and the description explains relative-vs-absolute time selection. However, it never states when to prefer this over the many sibling log-search tools, nor any prerequisites beyond 'uses AWS profile credentials'.

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 openWorldHint=false, so safety behavior is covered. The description adds filtering context through the prefix/format sentence and example, but does not add much beyond that, such as pagination expectations or repository scoping caveats.

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 two concise sentences, front-loads the core action, and uses the example efficiently. There is no redundant or wasted text.

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 tool has nine parameters but full schema coverage, an output schema, and read-only annotations, so the description does not need to explain all parameters or return values. It is nearly complete, though it would be stronger with an explicit note on when to use aws_codeartifact_versions instead.

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

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

Schema description coverage is 100%, so all nine parameters are already documented in the schema. The description mentions prefix and format filtering and gives an example involving domain, repository, npm format, and prefix, but it does not add significant meaning 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 states a specific verb and resource: list packages in a CodeArtifact repository, with optional prefix/format filters. It is clear enough to distinguish the operation generally, but it does not explicitly differentiate itself from the sibling aws_codeartifact_versions tool.

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

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

It gives clear usage context: list packages in a repository and optionally filter by prefix or format, reinforced by a concrete example. It lacks explicit when-not guidance or an alternative such as aws_codeartifact_versions.

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 openWorldHint=false, so safety is covered. The description adds useful behavioral context: it names the fields returned and describes the auto-normalization behavior for @scope/name inputs, though it omits pagination/maxResults 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?

Purpose and return fields are front-loaded, followed by the tricky npm-scope guidance. The scoped-package rule is stated twice (explicit instruction plus auto-normalize note plus example), which is slightly redundant but not wasteful.

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

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

With an output schema available, the description needn't explain return shape, and the schema covers the remaining parameters (region, profile, maxResults, context_id). The description adequately addresses the one genuinely tricky input case (npm scoping), making it complete 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%, so all nine parameters are documented in the schema itself, including the namespace and packageName scoping rules. The description reinforces the packageName/namespace handling with an example but adds little beyond what the schema already states, so 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+resource ('List versions of a package in CodeArtifact') and enumerates the returned fields (version, status, revision), which clearly distinguishes it from the sibling aws_codeartifact_packages tool that lists packages rather than versions.

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 a concrete invocation example and explains how to handle npm scoped packages, which implies when this tool is appropriate, but it never states when to use it versus aws_codeartifact_packages or any prerequisites.

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 carry readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real value beyond them by stating that no item data is returned and that the logged-in AWS session is used (i.e., no credentials need to be supplied). It stops short of describing throttling or error behavior, but nothing material is missing for a read-only metadata call.

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

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

Three short sentences, front-loaded with the returned fields, then the exclusion, then the routing hint. Every clause carries information; nothing is padding.

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?

An output schema exists, so return values need not be explained, and the auth model plus data-scope limits are stated. Minor gap: it doesn't note how region/profile are resolved when omitted, which matters given those optional parameters in a multi-account setup.

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 all four parameters (tableName, region, profile, context_id) are already documented in the schema. The description adds no syntax, defaulting, or format guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (describe DynamoDB table) and enumerates exactly what is returned: key schema, GSIs/LSIs, status, approximate size. The 'No item data' clause draws a hard line between this tool and aws_dynamodb_query, so an agent can distinguish them 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?

'Prefer before aws_dynamodb_query when keys are unknown' names the concrete alternative and the condition that selects it, which is precisely the decision an agent faces here. The negative scope statement ('No item data') reinforces when not to use it.

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

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

Annotations already declare readOnlyHint/destructiveHint/openWorldHint, so safety is covered. The description adds auth context ("Uses the logged-in AWS session") and the API-surface limitation (no Scan), which are traits beyond the annotations; it does not discuss result size or pagination behavior, but the 100-item cap is already in the schema.

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

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

Three short sentences, front-loaded with the capability and its boundary, then the requirement, then the alternative. No sentence is filler and nothing is buried.

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

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

With 13 parameters, a full output schema, and 100% schema coverage, the description only needs to carry intent, requirements, and routing — which it does. It stops short of explaining pagination or index-selection nuances, but those are documented per-parameter.

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

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

Schema description coverage is 100% and every parameter carries its own description with examples, so the baseline is 3. The description only restates that keyConditionExpression and expressionAttributeValues are required and hints at the partition/sort key shape — no syntax or format detail beyond what the schema already supplies.

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 ("Query a DynamoDB table or index") and immediately bounds the scope with "Query API only — Scan is not supported," which separates it from the describe/scan siblings. An agent knows exactly what operation this performs without opening the schema.

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

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

Names a concrete prerequisite path ("Prefer aws_dynamodb_describe_table first if key names are unknown") and states the hard requirement that keyConditionExpression and expressionAttributeValues are mandatory. It lacks an explicit negative case beyond Scan, but the routing advice is actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered by structured data. The description adds real value beyond that — result ordering and the fields returned (tags, digest, push date, size) — but says nothing about pagination, whether maxResults truncates silently, or what happens when the repository is empty or missing.

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

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

Three short sentences with the core behavior front-loaded and no filler. The example sentence is somewhat redundant with the repositoryName schema description (which uses the same 'your-tenant-storefront' sample) but it does clarify intent cheaply.

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 read-only list tool with an output schema and full schema coverage, the description covers what it does, how results are ordered, and what fields come back. The remaining gap — truncation behavior at maxResults and error cases for nonexistent repositories — is minor but not fully negligible.

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 region, profile, context_id, maxResults and repositoryName are all documented in the schema itself. The description only restates the repositoryName example and the sort order, adding no meaning to maxResults truncation semantics or region/profile precedence — baseline 3 applies.

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

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

States a specific verb and resource ('List images in an ECR repository') plus the ordering ('sorted by date, most recent first'), which is enough to distinguish it from aws_ecr_repos (which lists repositories rather than images). It never names that sibling explicitly, so the differentiation is inferred from the resource noun rather than stated.

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

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

Usage is implied by the required repositoryName parameter and the imagery of the example, but there is no explicit 'use this when...' guidance, no exclusions, and no mention of when to prefer aws_ecr_repos or another image-inspection path. An agent can infer the context but must do the routing work itself.

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 openWorldHint=false, and the description does not contradict them. However, it adds no behavioral context beyond the annotations, such as pagination behavior, maxResults truncation, or any other operational trait.

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 two short sentences with the core purpose front-loaded and no wasted wording. The example is brief and directly illustrates the optional name filter.

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 read-only list tool with full schema coverage, annotations, and an output schema, the description is mostly complete. It could be stronger by mentioning the related aws_ecr_images tool for listing images within a repository.

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 region, profile, context_id, maxResults, and namePrefix. The description only restates the optional name filter and adds no syntax or semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: 'List available ECR repositories,' with optional name filtering. It clearly distinguishes repositories from sibling tools like aws_ecr_images, though it does not explicitly mention that sibling as an 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 example 'list ECR repos containing storefront' implies usage for name-filtered listing, but the description does not state when to use this tool versus aws_ecr_images or other AWS listing tools. Guidance is present only by implication.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely new context by disclosing that env var values are redacted and that it looks for specific failure signals (OOM, public invoke, deprecated runtime). It stops short of describing scope of the IAM/CloudWatch calls or failure modes.

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

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

A single dense sentence front-loads the action and target, then lists evidence and constraints (redaction, read-only). Efficient, though the compressed parenthetical list is slightly harder to parse than separate clauses would be.

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?

An output schema exists, so return values need not be explained, and the description covers what is inspected. The main residual gap is auth/prerequisite context (profile/SSO), which matters for an AWS tool but is left implicit.

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

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

Schema description coverage is 100%, with each parameter (hours, logTail, region, profile, context_id, functionName) documented inline, so the schema carries the semantic load. The description adds nothing beyond the schema — e.g. no note on how hours/logTail interact with the signals reported — so the baseline 3 applies.

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

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

States a specific verb (diagnose) and resource (Lambda backing a Bedrock Agent action group) and enumerates the evidence it collects (config, IAM policies, CloudWatch errors, signals). It is distinguishable from the similarly-named aws_bedrock_agent_diagnose by naming Lambda as the target, though it never explicitly contrasts the two.

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

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

The description implies usage — troubleshooting a Lambda that backs an agent action group — and notes 'Read-only,' but it gives no explicit when-to-use/when-not guidance, no mention of prerequisites such as an active AWS SSO session or profile, and no routing advice versus aws_bedrock_agent_diagnose or aws_cloudwatch_logs_search.

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 beyond readOnlyHint by disclosing the auth model (logged-in AWS session for IAM, secretArn for DB creds) and the enforced SQL allowlist (SELECT/WITH/SHOW/DESCRIBE/EXPLAIN) with implied write rejection. It does not mention result truncation behavior or rate limits, though maxRows is in the schema.

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

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

Six short sentences, front-loaded with the action and transport, then requirements, then exclusions, then sibling preference. Nothing redundant with the title.

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

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

For a 9-param query tool with an output schema and full annotation coverage, the description supplies the operational context (enablement prerequisite, credential sourcing, statement allowlist) an agent needs. Missing only result-size/truncation expectations, which maxRows partially covers in the schema.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real semantics by tying resourceArn to the Aurora cluster, secretArn to Secrets Manager DB credentials, and explaining the Data API requirement that gives these params meaning. It skips region/profile/context_id, all of which the schema already covers.

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

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

Specific verb + resource + transport: 'Run read-only SQL against Aurora via the RDS Data API (HTTPS; no VPC TCP)'. It distinguishes itself from aws_cli_query and from Data-API-less RDS by name, so an agent can route 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?

States explicit preconditions (Data API must be enabled, not for classic RDS without Data API) and names the alternative: 'Prefer over aws_cli_query for SQL data during incidents.' That is when-to-use, when-not, and sibling routing in one paragraph.

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/destructive=false, but the description adds real value: 'one page' (ListObjectsV2 pagination constraint), 'does not download object bodies', and 'uses the logged-in AWS session'. These are behavioral facts not derivable from the annotations, though maxKeys/default paging depth details are left to the schema.

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

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

Four tight sentences, front-loaded with the core action, each earning its place (scope, sibling routing, body-download exclusion, session context). No filler, though slightly more compact phrasing is possible.

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 an output schema present and full annotation/parameter coverage, the description supplies the key behavioral gaps (one-page listing, no body download, session use). Adequate for correct invocation; only minor paging/follow-up behavior is left implicit.

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

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

Schema description coverage is 100%, so all eight parameters are already documented, including key overriding prefix. The description reinforces bucket+prefix/key but adds no syntax, region, or pagination semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('List objects in an S3 bucket') with the two lookup modes (prefix or exact key), and explicitly contrasts itself with the aws_cli_query sibling. An agent can distinguish it from other AWS tools without opening the schema.

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

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

'Prefer this over aws_cli_query for finding keys' gives an explicit alternative and the condition selecting this tool. The 'Provide bucket + prefix or key for the account/environment' line adds the invocation 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 declare readOnly, non-destructive and not-open-world, so the safety profile is covered structurally. The description still adds real value by disclosing that the secret VALUE is not returned and by listing the exact metadata fields an agent will get back, which prevents a wasted follow-up call.

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 tightly packed sentences: capability, exclusion, and worked example, with the most important information front-loaded. No filler.

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

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

For a simple read-only describe call with an output schema and full annotation coverage, the description covers purpose, exclusion, and examples adequately. Only the relationship to the sibling list tool is left implicit.

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

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

Schema description coverage is 100% with all four parameters documented, so baseline is 3. The description only echoes the secretId example format already present in the schema and says nothing about region/profile/context_id 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?

States a specific verb (verify existence) plus resource (secret in AWS Secrets Manager) and enumerates the metadata returned (name, ARN, rotation, tags, dates). The 'does the secret X exist?' framing makes clear this is a single-secret lookup rather than the bulk listing done by aws_secretsmanager_list.

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

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

The example question ('does the secret prod/storefront/api-key exist?') gives a concrete trigger condition, and the negative constraint 'Does NOT return the secret value' steers the agent away from expecting a payload. It stops short of naming the sibling (aws_secretsmanager_list) or any alternative for retrieving the value.

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 openWorldHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact — that secret values are never returned — but says nothing about pagination or the maxResults default truncation, which matters for a list tool.

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

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

Three short sentences, front-loaded with the core action and immediately followed by the most important constraint (no values). The quoted example is useful; nothing 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?

An output schema exists, so return-value shape need not be described, and the annotations cover safety. The main residual gap is pagination/truncation behavior for a tool capped at 100 results, which the description never mentions.

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 region, profile, context_id, maxResults and nameFilter is already documented. The description only echoes the name-filter behavior, adding no format or example syntax beyond the schema, which is the expected baseline when the schema does the work.

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 ('List') and resource ('secrets in AWS Secrets Manager') plus the filter scope, and clarifies it returns metadata only, which implicitly distinguishes it from aws_secretsmanager_describe. It does not explicitly name that sibling, so an agent still has to infer which one to pick when it wants details.

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 'Does NOT return values, only metadata' line and the example imply when this tool is appropriate, but there is no explicit statement of when to use it versus aws_secretsmanager_describe or what happens when the list is truncated. Usage is inferable rather than spelled out.

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=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by clarifying that it starts or renews a session without restarting the server, but it omits auth-flow details, expiry behavior, and side effects of renewing a session.

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 front-loaded sentence with no wasted words. It states the action and a key constraint immediately, making it easy to scan.

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?

An output schema exists, so return values need not be explained. However, given the crowded family of AWS SSO login tools, the description is too thin to fully help an agent choose this variant or understand the session renewal lifecycle; it is minimally adequate but incomplete for the tool's context.

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

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

Schema description coverage is 100%, so both the required 'profile' and optional 'context_id' parameters are fully documented in the schema. The description only echoes 'for a profile' and adds no syntax or selection guidance beyond what the schema provides; 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 gives a specific verb+resource ('Start/renew the SSO session') and clarifies it works for a profile without restarting the server. It does not distinguish this tool from sibling login tools such as aws_sso_login_device_start, aws_sso_login_remote, or aws_sso_login_global_start, leaving ambiguity about which login entry point to select.

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?

There is no explicit guidance on when to use this tool versus the many sibling login variants. The parenthetical 'without restarting the server' implies renewal, but no exclusions, prerequisites, or alternatives are named, so the agent must infer usage from tool names.

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 useful context beyond the annotations by explaining that user-scoped sessions are stored encrypted in PostgreSQL while legacy local sessions use the AWS filesystem cache. However, it does not explain why the operation is non-read-only, what side effects polling may have, or whether there is a required polling cadence.

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 and front-loads the primary action in the first sentence. The second sentence adds storage context without excessive length, though it is somewhat tangential to the immediate invocation.

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 output schema and annotations cover return values and safety signals, and the input schema fully documents the parameters. Still, the description does not route the agent among the several SSO login siblings or explain the expected polling lifecycle, which are meaningful gaps for an authentication tool.

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

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

Schema description coverage is 100%, and both parameters are fully documented in the input schema. The description does not add meaning beyond the schema, so the baseline score 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 uses a specific verb and resource: polling the device_code status and verifying that AWS role credentials are usable. It is clear what the tool does, though it does not explicitly differentiate itself from siblings such as aws_sso_login_device_start or aws_sso_login_global_poll.

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 phrase 'Poll the device_code status' implies this is a follow-up step after obtaining a device_code, but the description does not explicitly say when to use it, when not to use it, or how it relates to alternative SSO login tools.

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 the tool is not read-only and not destructive. The description adds valuable behavioral context: it returns a deviceCode for polling and conditionally returns 'already_authenticated' if a session exists, without starting a new login. It does not cover error cases or permissions, but the annotations lower the bar.

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. The module clarification is front-loaded, followed by the core action and then a key conditional behavior. Every sentence earns its place and is easy to parse.

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

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

Given the presence of an output schema, annotations, and full schema descriptions, the description covers the essential purpose, return value (deviceCode), and conditional behavior. It could mention what to do after receiving the deviceCode, but the polling step is referenced implicitly via 'for polling' and a sibling tool exists.

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 both parameters (profile and context_id) are fully documented in the schema. The description does not add any parameter-specific meaning beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description states a specific verb ('Start') and resource ('Device Code flow for SSO') and clarifies the module ('aws (not aws-sessions)'). It also mentions the return value (deviceCode) and a conditional behavior, making it easy to distinguish from siblings like aws_sso_login_device_poll or aws_sso_login_global_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?

The description implies usage by stating 'If a valid session already exists, returns status already_authenticated without starting a new login,' which gives a condition for calling it. However, it does not explicitly name alternatives like aws_sso_login or aws_sso_login_global_start or state when to prefer this tool over them.

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 frames the operation as polling status and returning aggregated status, which strongly implies a read-only check. The annotations declare readOnlyHint=false, creating an annotation contradiction: an agent cannot tell whether this polling has side effects or state-changing behavior.

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

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

One front-loaded sentence states the action, resource, batch scope, and aggregated return values. There is no wasted text.

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

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

For a two-parameter polling tool with an output schema, the description is largely complete: it says what is polled and what status classes are returned. It omits when-to-use guidance and any side-effect disclosure, but return-value detail is appropriately left to the 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 description coverage is 100%, so the schema already documents device_codes and context_id. The description reinforces that multiple device_codes are processed in batch, but adds no format, source, or handling details 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?

States a specific verb and resource: poll the status of multiple AWS SSO global device_codes. The batch/global scope distinguishes it from single-device SSO polling tools without needing the sibling name.

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?

Implies usage by saying it polls multiple device_codes in batch, which suggests use after a global login start. However it does not explicitly state when to use it versus aws_sso_login_device_poll or other SSO siblings, nor does it list prerequisites or exclusions.

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

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

With annotations already declaring non-readonly, non-destructive, non-open-world behavior, the description adds useful context: it returns a batch with device code logins (flow_type=device_code_batch) and resolves omitted profiles from the cloud catalog. It does not state auth prerequisites or whether starting a login creates persistent state, but the added return-flow detail is meaningful 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?

The description is three tight sentences, front-loaded with the action and scope, followed by default resolution and return shape. Every sentence contributes information without repetition.

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 operation, default resolution, and return shape, which is adequate given the output schema and annotations. However, it omits explicit guidance on choosing this tool over the several other SSO login siblings, leaving a meaningful selection gap for an agent.

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 three parameters. The description restates the profiles default behavior and adds 'typically nonprod + prod' context, but does not clarify dedupeBySsoSession or context_id beyond what the schema provides. Baseline 3 applies when the schema carries parameter documentation.

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 gives a specific verb and resource ('Start remote SSO login') plus a scope ('global coverage, typically nonprod + prod SSO profiles'). It does not explicitly name the sibling alternatives (e.g., aws_sso_login_remote, aws_sso_login_device_start) that an agent must choose between, so differentiation is implied rather than stated.

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

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

The only usage rule is 'When profiles are omitted, uses SSO profiles from the cloud catalog for this tenant', which is parameter default behavior rather than when to choose this tool over siblings. The name and title imply global login, but there are no explicit when/when-not conditions or 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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so safety is partially covered. The description adds that no browser opens and flow type is detected, but it omits the multi-step consequence, such as needing a follow-up poll tool, and does not describe session/token side effects.

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, and the key action plus remote constraint is front-loaded.

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

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

An output schema exists, so return shape need not be explained. However, for an SSO login starter in a family of start/poll tools, the description does not explain the follow-up step or how the returned flow information maps to the device/global poll siblings, leaving an important workflow gap.

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 both profile and context_id are documented in the schema. The description adds no parameter-level meaning beyond that, which is the baseline expectation when the schema is fully described.

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: 'Start SSO login,' with the scope 'without opening a browser,' and adds that it detects Device Code versus OAuth PKCE. This distinguishes it from a browser-based sibling, but it does not explicitly name which sibling to use for each detected flow.

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

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

Gives a clear usage context (browserless login) but does not say when to use this instead of aws_sso_login, aws_sso_login_device_start, or aws_sso_login_global_start. The agent must infer the routing from the detected flow type.

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 openWorldHint=false, so the safety profile is covered. The description adds only the returned fields (Account/Arn); it does not say what happens when the profile is unauthenticated or expired (error vs. login prompt), which is the key behavioral question for an STS identity call.

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

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

A single front-loaded sentence with the core purpose first and the optional input in parentheses; no filler. Only the slightly awkward parenthetical phrasing keeps it from being maximal.

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 annotations covering safety, a full schema and an output schema, the description is adequate but incomplete on the operationally important point: how this tool behaves with missing/invalid credentials and whether it interacts with the SSO login flow. For a two-parameter read tool that is a moderate gap rather than a fatal one.

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

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

Schema description coverage is 100% for both parameters, so the schema carries parameter documentation. The description only restates that profile is optional and says nothing about context_id or what omitting profile falls back to (default/ambient credentials) — baseline 3 applies.

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

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

States a concrete verb and resource — 'Show the current identity (Account/Arn)' — plus the scoping input (profile). It is clearly distinguishable from the aws_sso_login_* siblings, which perform authentication rather than identity reporting, though it never names those siblings explicitly.

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

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

There is no guidance on when to call this versus alternatives such as aws_sso_login or aws_sso_login_device_start, nor any stated precondition (e.g. 'call this to verify credentials before other aws_* tools'). The only usage hint is that profile is optional, which the schema already conveys.

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 and non-destructive, so safety is covered; the description adds genuinely new behavior: results are a single page (no auto-pagination), nothing is downloaded, and it requires Storage Blob Data Reader on the container. Missing is what happens when a page is truncated or how to continue.

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

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

Three short sentences: what it does, when to prefer it, what it requires. Zero filler and each clause carries information an agent needs.

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 an output schema present, return values need not be explained, and the description covers scope, safety-adjacent behavior (read-only, single page), and the permission prerequisite. The one gap is pagination continuation, which matters for a capped 200-result listing but is partly mitigated by naming maxResults in the schema.

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

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

Schema description coverage is 100%, so every parameter including key/prefix semantics, maxResults bounds, and tenant defaults is already documented. The description's 'prefix or exact key' phrasing restates what the schema says rather than adding format or interaction details, so the baseline 3 applies.

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

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

States a specific verb (lists) plus resource (blobs in an Azure Storage container) and scopes it to prefix or exact key matching, single page, no download. That is enough to distinguish it from the general azure_cli_query sibling without opening a schema.

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

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

Explicitly names the alternative and the condition that selects it: 'Prefer this over azure_cli_query for finding blob keys during incidents.' It does not state exclusions (e.g. when azure_cli_query is still the better call, or when to use prefix vs key).

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/destructiveHint=false, but the description adds substantive behavior: an explicit allowlist of read verbs and an explicit exclusion of secret-value reads, which the annotations do not convey. It stops short of mentioning permission prerequisites, throttling, or how command failures surface.

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

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

Three tight sentences: capability first, constraint second, concrete examples last. No redundancy or filler; every sentence carries decision-relevant information.

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

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

With an output schema present, full parameter documentation, and annotations covering safety, the description needs only to define scope and constraints, which it does. The one missing piece is routing guidance against more specific Azure tools, which matters given the crowded sibling set.

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 all three parameters are already documented in the schema. The description repeats the command-format hint (no leading 'az') and gives example command strings, but adds no new semantics for context_id or azure_tenant_id. Baseline 3 applies.

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

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

States a specific verb and resource ('executes any read-only Azure CLI command') and bounds the scope with a verb allowlist plus examples. It is clear what the tool does, but never contrasts itself with the many specialized Azure siblings (azure_resource_groups, azure_servicebus_namespaces, azure_blob_find) that cover a subset of the same ground.

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 allowed-verb list ('list, show, get, describe, check, verify…') and the prohibition on write/delete/secret-value operations give real guidance on when the tool is usable. However, there is no instruction on when to prefer a specialized sibling over this generic escape hatch, which is the key routing decision for an agent facing ~200 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the two output modes driven by presence/absence of zone, and the public/private zone distinction. Missing auth/rate-limit notes, but strong for a read tool 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?

Three tight sentences, front-loaded with the core action, then the two modes, then a scoping note. No filler; every clause carries information.

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

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

With an output schema and full schema coverage, the description needn't explain return values. It adequately covers purpose, modes, and zone types. A minor gap is not clarifying the relationship to the generic dns_lookup/cf_dns_records siblings.

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

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

Schema coverage is 100%, so all seven parameters are already documented in the schema. The description reinforces how zone (optional) flips behavior between listing zones and listing record sets, and mentions recordType/hostname filtering, but adds little beyond what the schema's own descriptions provide. 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?

States a specific verb+resource (queries Azure DNS zones and record sets) and scopes it to Azure, which distinguishes it from cf_dns_records and dns_lookup implicitly. However, it never names those siblings explicitly, so the differentiation relies on the agent inferring 'Azure' means not-Cloudflare/not-generic.

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 conditional branching: without zone -> list zones, with zone -> list record sets (optionally filtered). This is genuine when-to-use guidance for the tool's own modes. It stops short of routing the agent away from the generic dns_lookup or cf_dns_records siblings.

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, openWorldHint=false, so the safety profile is covered; the description still adds real behavior the annotations do not — that the payload never includes the secret value, and that a common substitute path is blocked. It does not discuss auth/tenant requirements beyond the schema's own default note, keeping it just short of a 5.

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

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

Two sentences, zero filler, with the core scope statement front-loaded and the routing/exclusion rules following. Every clause carries decision-relevant 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?

An output schema exists and all parameters are documented, so the description only needs to supply scope, ordering, and the blocked-alternative caveat — all of which it does. Nothing an agent needs to call this 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% with all four parameters documented, so the baseline is 3. The description reinforces that lookup is by name rather than versioned URI, but that meaning is already present in the secretName schema description, so it adds little beyond it.

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

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

States a specific verb and resource ('Returns metadata for a single Key Vault secret by name') and immediately scopes the result by excluding the secret value. An agent can distinguish it from the bulk list tool and from any value-retrieval path without opening the schema.

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

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

Gives an explicit alternative ('Prefer this over azure_cli_query("keyvault secret show …") which is blocked') with the reason, plus a required precursor ('List names first with azure_keyvault_secrets_list'). Both the when and the ordering are spelled out rather than inferred.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description's added value is the explicit 'never returns secret values' guarantee, which prevents an agent from expecting secret material. It does not mention required vault permissions/RBAC or pagination-cursor handling, which would complete the behavioral picture.

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

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

Three short sentences, no filler, with the most important constraint (metadata-only) front-loaded in the first sentence and the two routing hints following immediately.

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

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

An output schema exists, so return values need not be explained, and all four parameters are covered by the schema. The only remaining gap is auth/prerequisite context (vault access requirements, cross-tenant behavior given the optional azure_tenant_id), which would make it fully self-contained.

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

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

Schema description coverage is 100%, with vaultUrl, context_id, maxResults (with default 50 / max 200) and azure_tenant_id all documented inline. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Lists secret properties in a Key Vault') and immediately qualifies the scope with 'metadata only — never returns secret values'. It names both the sibling it replaces for discovery (azure_cli_query) and the sibling for single-secret lookups (azure_keyvault_secret_metadata), so it is unmistakable.

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

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

Gives explicit routing: 'Prefer this over azure_cli_query for Key Vault discovery' and 'Use azure_keyvault_secret_metadata for a single secret.' Both the preferred alternative and the inverse case are stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint/destructiveHint, but the description adds real context: the delegated-session prerequisite and the fact that a guard blocks mutations, so the agent knows a write attempt will fail rather than silently no-op. It does not disclose rate limits or result-size behavior beyond what the schema's maxRows carries.

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

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

Three short sentences with the purpose front-loaded, followed by routing and then prerequisites — a sensible order. Minor redundancy: read-only is asserted in the opening sentence and again in the closing guard 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?

With annotations, a full output schema, and 100% parameter coverage, the description supplies the remaining pieces an agent needs: when to prefer it and what session state is required. It stops short of explaining workspace resolution or context_id behavior, but those are schema-documented.

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

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

Schema description coverage is 100% and every parameter (kql, timespan, startTime/endTime, maxRows, context_id, workspaceId, azure_tenant_id) is documented in the schema itself. The description adds nothing about parameter syntax or the timespan-vs-start/end tradeoff, so baseline 3 applies.

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

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

States a specific verb (executes) and resource (KQL query against a Log Analytics workspace) plus the read-only scope, which immediately distinguishes it from the general azure_cli_query sibling. An agent can select it without opening the schema.

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

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

Explicitly routes the agent: 'Prefer this over azure_cli_query for App Insights / Log Analytics incidents' names the alternative and the condition that selects it. It also states the prerequisite (an active Azure delegated session via azure_user_login_start), covering the main failure mode.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description only adds that the listing is unfiltered ('all available'), but says nothing about which subscription/tenant the groups come from or whether azure_subscription_set affects the result.

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

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

A single front-loaded sentence with zero filler. It is, however, arguably too terse for a tool whose output scope depends on tenant/subscription context.

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?

An output schema exists and parameters are fully documented, so much of the burden is carried structurally. Still, for a cross-tenant Azure listing tool, the description omits which tenant/subscription the 'available' groups belong to and how to switch scope — a meaningful gap.

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 both optional parameters (context_id, azure_tenant_id) are already documented, and the description adds nothing about them. Baseline 3 applies 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.

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

Specific verb+resource ('Lists ... resource groups') with an explicit scope word ('all available'). It does not distinguish itself from nearby siblings such as azure_subscriptions_list or azure_servicebus_resourcegroup_detect, so it falls short of a 5.

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?

There is no when-to-use guidance, no mention of prerequisites (subscription/tenant context, auth state), and no routing to alternatives like azure_servicebus_resourcegroup_detect when the goal is detecting a resource group for a Service Bus namespace.

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 closed-world scope, so the safety profile is carried. The description adds that the read goes through the Azure Service Bus SDK, which explains why content is 'real', but it omits the behaviorally critical point of whether the SDK read peeks or receives/dead-letters messages, and says nothing about auth or subscription requirements for a 9-parameter tool.

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

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

A single front-loaded sentence with no wasted words. It is efficient, though arguably under-specified rather than tight — the brevity comes at the cost of routing and behavioral detail.

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?

An output schema exists, so return values need not be explained, and the schema is fully described. Still, for a 9-parameter tool sitting among many near-identical Service Bus siblings, the description leaves the agent without the queue/topic distinction or the reason to pick this over adjacent tools.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description adds no syntax, format, or constraint detail beyond the schema and does not explain the queueName vs topicName/subscriptionName relationship, so the baseline 3 applies.

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

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

The description names a specific verb (Reads) and a specific resource (Dead Letter Queue message content), and the phrase 'real content' hints that this returns payloads rather than metadata. However, it never names the sibling tools it must be distinguished from (e.g. azure_servicebus_queue_deadletter or azure_servicebus_message_explorer), so the agent has to infer the split itself.

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?

There is no statement of when to use this versus the dead-letter or message-explorer siblings, no prerequisites, and no exclusions. The only guidance is implicit in the word 'real', which is not enough to route an agent reliably among a dozen Service Bus tools.

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

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

Annotations already declare this as a read-only, non-destructive, closed-world query. The description adds that it spans all Service Bus environments and can be scoped by environment, which is useful scope information, but it does not explain aggregation behavior, what 'general health' means, or permission requirements.

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

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

Two sentences, front-loaded with the core action and scope, with no wasted words. The optional filter is stated immediately after the primary behavior.

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 tool is simple and has an output schema, so return-value detail is not required. However, the description does not resolve the overlap with azure_servicebus_namespace_health or clarify whether 'all Service Bus environments' means the dev/tst/pre/prod environment dimension or Azure namespaces.

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 context_id, environment, and azure_tenant_id. The description restates the environment enum values and the 'all' option but adds nothing about tenant defaulting or context handling beyond what the schema provides.

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

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

States a clear verb and resource: show general health status of all Service Bus environments, with optional environment filtering. It is understandable, but it does not differentiate itself from the sibling azure_servicebus_namespace_health, which plausibly covers similar ground.

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 says the environment filter is optional and can be 'all', which gives minimal usage context. It does not say when to prefer this over azure_servicebus_namespace_health or azure_servicebus_monitoring_report, even though those siblings clearly overlap.

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 openWorldHint=false, so the safety profile is covered. The description adds the notion of 'full details' (rich message body/properties rather than counts), but says nothing about whether peeking is non-destructive on the broker side, the maxMessages cap of 20, or ordering/truncation behavior — all relevant for a message-inspection tool.

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

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

One short sentence, front-loaded with verb and resource, with zero filler. It is arguably too terse for a nine-parameter tool, which is why it falls short of 5 — brevity here edges into under-specification rather than pure efficiency.

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?

An output schema exists, so return values need not be explained. But for a nine-parameter tool with mutually exclusive queue/topic addressing and a dead-letter mode that duplicates a dedicated sibling, the description leaves key selection decisions unaddressed. The agent has to open the schema and cross-read sibling names to call this 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 all nine parameters are documented in the schema itself and a baseline of 3 applies. The description adds no extra semantics beyond that — it does not explain that queueName and topicName are alternative addressing modes, nor mention subscriptionName or the dead-letter toggle.

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 concrete verb and resource: 'Inspects messages in queues and topics with full details.' That is clearly a read/peek operation on Service Bus messages, and the GUI analogy reinforces the 'show me everything' intent. However, it never distinguishes itself from siblings that also surface message content, notably azure_servicebus_dlq_content and azure_servicebus_queue_deadletter, which the peekDeadLetters parameter overlaps with.

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?

There is no when-to-use guidance at all — nothing says to reach for this instead of azure_servicebus_queues (discovery), azure_servicebus_queue_metrics (counts), or azure_servicebus_dlq_content (dead letters). The only hint is the GUI comparison, which is descriptive rather than directive. The agent must infer routing from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the report aggregates queue and topic dead letter counts, which is useful scope information, but says nothing about report format, size, latency, or whether it queries live vs cached data.

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

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

A single front-loaded sentence with no filler; the parenthetical efficiently names the report's contents. It is perhaps overly terse given the dense sibling namespace, but every word 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?

An output schema exists so return values needn't be described, and all three parameters are optional and documented. What is missing is the differentiation from the crowded azure_servicebus_* family, which is the main thing an agent needs to call this 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% (context_id, environment, azure_tenant_id are all documented with auto-detection behavior), so the schema carries parameter meaning. The description adds nothing about parameters, which is acceptable at full coverage and yields 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?

States a specific verb ('Generates') and resource ('Service Bus report') and scopes the content to queues and topics with dead letter counts. However, it does not distinguish this from the many sibling Service Bus tools (azure_servicebus_health_overview, azure_servicebus_queues, azure_servicebus_topics, azure_servicebus_dlq_content), so an agent cannot tell from the description which one to pick.

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?

No guidance on when to use this report versus azure_servicebus_health_overview or the individual queues/topics tools. The word 'automatic' is not explained (scheduled? on-demand?) and there are no prerequisites or exclusions stated.

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 openWorldHint=false, so the safety profile is covered. The description adds no behavioral context beyond that — not what "health" comprises, not whether it needs an authenticated Azure session or a resolved subscription, not how it differs from the overview tool.

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

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

A single short clause with no filler and the resource front-loaded. It is efficiently written; the problem is under-specification, not verbosity.

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?

An output schema exists, so return values need not be explained, and the annotations cover safety. However, for a tool sitting in a dense cluster of overlapping Service Bus and health-overview tools, the description leaves the selection problem entirely unaddressed, which is the main thing an agent needs here.

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

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

Schema description coverage is 100% and all four parameters (namespace, resourceGroup, context_id, azure_tenant_id) are documented in the schema itself. The description adds nothing about parameter semantics, so the baseline 3 applies.

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

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

The description names a verb ("Gets") and a resource ("health and status information of a namespace"), so the basic intent is legible. But "health and status information" is vague about what is actually returned, and it does nothing to distinguish this tool from close siblings like azure_servicebus_health_overview, azure_servicebus_monitoring_report, or azure_servicebus_namespaces.

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?

There is no when-to-use guidance, no prerequisites (e.g. an active Azure session), and no exclusion pointing at the sibling health/overview tools. An agent choosing among a dozen azure_servicebus_* tools gets no help from this sentence.

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 openWorldHint=false, so the safety profile is fully covered without the description's help. The description adds nothing beyond that – no indication of scope (current subscription only, or all subscriptions the tenant can see), pagination, or cost of the call. An output schema exists, so return-shape disclosure is not required, making a 3 the right level.

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

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

A single front-loaded sentence with no filler or redundancy. It is appropriately sized, though the brevity is achieved partly by omitting scope detail that would have earned additional value.

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 an output schema and full annotation coverage, the description only needs to establish scope and role in the workflow. It leaves the tenant/subscription scope of 'all available' undefined, which is a real ambiguity given the azure_tenant_id and context_id parameters.

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

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

Schema description coverage is 100%, with context_id and azure_tenant_id both documented in the schema itself, so the baseline is 3. The description adds no meaning about how these parameters affect which namespaces are returned, which is the one place extra text would have helped.

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 ('Lists all available Service Bus namespaces'), which is unambiguous on its own. It does not, however, differentiate itself from the dense family of siblings (azure_servicebus_queues, azure_servicebus_topics, azure_servicebus_namespace_health), so an agent gets no signal that this is the discovery entry point those tools depend on.

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?

There is no guidance on when to call this versus alternatives, no mention that it should be used first to discover a namespace before calling queue/topic tools, and no prerequisites such as an active Azure session. The agent must infer usage entirely from the name and the sibling list.

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 openWorldHint=false, so the safety profile is covered. The description adds only the '(failed messages)' gloss on dead-letter semantics and says nothing about what metrics are returned, time window, per-queue vs aggregate scope, or permissions — with annotations carrying the load, that is a thin addition.

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

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

A single front-loaded sentence with zero filler. It is efficient, though the brevity borders on under-specification rather than optimal tightness.

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 5-parameter tool inside a dense Service Bus tool family, the description does not say what the metrics represent or how they differ from queue_metrics/topic_sub_metrics. The output schema covers return values and annotations cover safety, but the routing information an agent needs to pick this tool is absent.

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

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

Schema description coverage is 100% and all five parameters (namespace, queueName, context_id, resourceGroup, azure_tenant_id) are documented in the schema itself. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (Gets) and resource (dead letter queue metrics), and the parenthetical '(failed messages)' clarifies what a dead-letter queue holds. It implies a distinction from azure_servicebus_queue_metrics and azure_servicebus_dlq_content but never names those siblings, leaving the boundary to inference.

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?

There is no when-to-use guidance, no prerequisite statement, and no mention of alternatives such as azure_servicebus_queue_metrics (normal queue metrics) or azure_servicebus_dlq_content (message payloads). The agent must guess which of the several Service Bus tools to call.

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 annotations already establish that this is a safe, read-only, non-destructive operation, so the description does not need to carry the full safety burden. It adds that the result covers messages, status, and configuration, but it does not disclose whether queue existence is required or how detailed or fresh the metrics are.

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 front-loaded sentence with no filler. The parenthetical list efficiently clarifies the scope of 'detailed metrics' without adding unnecessary length.

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

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

For a read-only metrics tool with full schema coverage, annotations, and an output schema, the description is minimally adequate. However, it does not help an agent choose this tool over closely related Service Bus queue tools or clarify what distinguishes these metrics from monitoring or health reports.

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

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

Schema description coverage is 100%, so every parameter is already documented in the input schema. The description does not add any further meaning about required parameters such as namespace and queueName or optional context/resource-group scoping, so the baseline score of 3 applies.

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

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

The description states a clear verb and resource: gets detailed metrics of a queue, with parenthetical examples of what those metrics include. It is distinguishable from generic queue-listing siblings, but it does not explicitly differentiate itself from other Service Bus queue-level tools such as queue_deadletter, monitoring_report, or health_overview.

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?

There is no guidance on when to use this tool versus alternatives. Given the many adjacent Service Bus tools, an agent must infer from the name whether this is for health, monitoring, dead-letter, or general queue 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 already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false and an output schema exists, so the safety profile is fully covered elsewhere. The description adds nothing beyond scope – no note on namespace-wide enumeration cost, pagination, or empty-result 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?

A single front-loaded sentence with zero filler. It is appropriately sized but borders on under-specified rather than padded, so it loses a point for thinness rather than verbosity.

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 read-only list tool whose annotations and output schema are rich, the description is minimally sufficient to call it correctly. It still omits how results relate to sibling queue-level tools and whether the namespace must be resolved first, leaving an agent to guess the intended workflow.

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 all four parameters (namespace, context_id, resourceGroup, azure_tenant_id) are already documented in structured form. The description mentions the namespace implicitly but adds no semantics beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Lists all queues') plus a scope ('in a namespace'), which implicitly separates it from the azure_servicebus_topics / topic_subscriptions siblings. It never names those siblings explicitly, so the differentiation is inferred rather than stated.

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

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

There is no when-to-use guidance, no prerequisites (e.g. that a namespace must be known first, likely via azure_servicebus_namespaces), and no routing to related siblings such as azure_servicebus_queue_metrics, azure_servicebus_queue_deadletter, or azure_servicebus_message_explorer.

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