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

With no annotations, this description carries the full burden and does it well: it discloses that reads, writes, deletes, and secret reads are all dispatched, that AWS IAM is the sole authorization boundary, that nothing is refused locally and AccessDenied is returned verbatim, that pagination is followed to completion, and that truncated results mean max_items should be raised. It also explains the blast-radius cap and the role-resolution rule, which are the non-obvious operational risks an agent must anticipate.

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?

It is front-loaded with purpose and the highest-risk facts (blast radius, no local refusal) appear early, with code formatting keeping the parameter examples scannable. It is slightly long and the account-selector discussion is compressed into one dense sentence that could have been split by parameter family.

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 shapes need not be described, and the mutation/authorization profile is thoroughly covered. The gap is the 17-parameter surface: with zero schema description coverage and no annotations, an agent still lacks the semantics of the many selector parameters needed to target accounts precisely rather than accidentally widening 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 0%, so the description must compensate, and it only does so partially: it explains service, operation, params (with an example Filters shape), region, max_items, and role. The ten account-selector parameters (org/orgs, account_id/account_ids, account_name/account_names, environment, name_contains, and both exclude_* variants) are covered only collectively as "account selectors," with no indication of whether they combine, are mutually exclusive, or which to prefer for a given targeting need.

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?

"Run one AWS API call across every account a selector resolves to" gives a specific verb (run/dispatch), resource (AWS API call), and scope (fanned out over resolved accounts). The concrete service/operation/params examples make it unambiguous what kind of input is expected, and no sibling tool does anything comparable.

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

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

It states clear operating context: region is always required and never defaulted, omitting selectors targets every account in the active org subject to the blast-radius cap, and role= overrides the deterministic TOML/sole-grant resolution. It never names an alternative sibling to use for account discovery (search_accounts, list_roles, explain_role_selection), so there is no explicit routing guidance, but the when-to-use context is otherwise solid.

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?

No annotations are supplied, but 'Report' strongly implies a read-only, side-effect-free inspection, which is the main behavioral fact an agent needs. It does not say what 'freshness' is measured against (TTL, last sync timestamp), whether the call hits upstream services, or what cost/latency to expect.

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 with no filler, and the scope distinction is packed into the same clause. It is arguably too terse for the only documentation of the tool, but nothing is wasted.

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 zero-required-parameter read tool with an output schema, this covers the essentials: what is reported and the two invocation modes. The remaining gap is the definition of 'freshness', which the output schema may itself disambiguate.

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 0%, so the description must carry the meaning of the single `org` parameter. It does explain the key distinction — supply an org for one scope, omit it for all configured orgs — which the schema alone (nullable string, default null) does not convey. It adds no format examples or matching semantics for the org value.

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

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

States a specific verb ('Report') and resource ('cache freshness') along with its scope ('one org, or every configured org'). An agent can distinguish it from siblings like refresh_accounts or org_status, though the description never explicitly names those alternatives.

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 only implied: the reader infers this is for checking data staleness before relying on cached results. There is no explicit when-to-use, when-not-to-use, or pointer to a sibling tool for refreshing versus inspecting.

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?

No annotations are provided, so the description carries the behavioral burden. It usefully discloses that the configuration is 'resolved, loaded' and 'never contains secrets,' and 'Show' implies a read-only operation. However, it does not mention permissions, side effects, or other operational traits beyond the secret exclusion.

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 unnecessary wording. Both the action and the key safety caveat are stated efficiently.

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 parameterless, and an output schema exists to describe return values. The description covers the essential context—resolved/loaded configuration and absence of secrets—though it could explicitly contrast with config_validate for fuller completeness.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain. The baseline score of 4 applies because the description cannot add meaning beyond an empty 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 uses a specific verb ('Show') and resource ('resolved, loaded configuration'), making the tool's purpose clear. It does not explicitly distinguish itself from the sibling config_validate tool, 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 explicit guidance on when to use this tool versus alternatives such as config_validate. The implied usage is to inspect the effective configuration, but no conditions, exclusions, or alternatives are named.

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 no annotations, the description does real work by disclosing the key behavioral trait: errors are reported but not applied, so the operation is non-destructive. It leaves residual ambiguity about whether a valid re-load actually takes effect in the running process and what happens if the file is missing or unreadable.

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 action comes first and the non-applying guarantee follows 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?

For a no-argument tool with an output schema, the description covers the action and its safety profile adequately. The remaining gap is the relationship to config_show and the prerequisite state of the config file.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing further the description could add on parameter meaning.

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

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

States a specific verb pair (re-load and validate) and resource (the config file), which is far more than a restatement of the name. It distinguishes the action from the sibling config_show (display) by emphasizing validation, though it never names config_show directly.

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 only implied: an agent can infer this is for checking config correctness after edits, but the description never says when to pick this over config_show or what precondition (e.g. a config file on disk) must hold. No exclusions or alternatives are offered.

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 no annotations, the description carries the full burden. 'Report' implies a read-only operation and 'if any' usefully signals the result may be empty, but it says nothing about permissions or session prerequisites. The presence of an output schema covers the return shape.

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 sentence with the key qualifier ('currently active', 'if any') front-loaded. No wasted wording and nothing buried.

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

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

For a zero-parameter read with an output schema documenting the response, the description is nearly sufficient. The one remaining gap is how it relates to sibling org tools, which would help an agent route 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?

The tool takes zero parameters, so there is nothing parameter-level for the description to explain. Baseline is 4 for a parameterless tool, and nothing here misleads about inputs.

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: 'Report the currently active org'. That clearly separates it from mutating siblings like use_org or login, though it does not explicitly name org_status or orgs_list as the alternatives an agent might confuse it 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?

Usage is only implied — an agent can infer this is the way to check which org is currently active. There is no statement of when to prefer it over org_status, orgs_list, or use_org, and no note about switching orgs first.

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 no annotations, the description carries the full burden and does well: it discloses that nothing is called remotely, that resolution is deterministic, and it enumerates the precedence chain (explicit override, TOML environment mapping, sole granted role). It does not state what happens when no role resolves or whether authentication is required, so it stops short of full coverage.

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 front-loaded sentences with no filler; the side-effect disclaimer leads and the resolution logic follows. The trailing clause 'without the model ever choosing a role itself' partially restates 'deterministic' and could be folded in, which keeps it just short of a 5.

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 described, and the description covers purpose, side effects, and resolution precedence for a moderately complex tool. The remaining gap is parameter-level meaning and the no-role-resolvable case, which matters for an explain tool whose whole value is the explanation.

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 0%, so the description must explain all four parameters. It only loosely ties 'role' to the explicit-override mechanism and 'org' to the TOML environment mapping; account_id vs account_name (why both are required) and the nullability/defaults of org and role are left entirely unexplained.

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 — dry-run deterministic role resolution for one account — and immediately separates itself from siblings by declaring it makes no service call and never lets the model pick a role. That distinguishes it from login, use_org, and list_roles without the agent needing to compare schemas.

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

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

The 'dry-run' and 'makes no service call' framing implies this is the inspection step to run before an actual role assumption, but no sibling is named as the alternative and there is no explicit when-not guidance (e.g. 'use use_org to actually assume the role'). Usage is inferable rather than 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?

No annotations are supplied, so the description carries the full burden. It reveals that roles come from the account's SSO portal, implying an external/auth-dependent lookup, but says nothing about caching, whether stale results can be returned, what force_refresh does, or what failure looks like — gaps that matter given a sibling cache_status and a force_refresh parameter.

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 repetition. It is efficient, though the brevity is partly the cause of the semantic gaps scored elsewhere rather than a model of completeness.

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?

Output values need not be explained because an output schema exists, but for an auth-dependent, cacheable lookup with an undocumented org selector and a cache-control flag, the description is too thin. An agent could call it but cannot reason about auth prerequisites, caching effects, or how org selection interacts with account_id.

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 0% across three parameters. The description implies account_id ('on one account') but gives no meaning for 'org' (nullable, defaults to null) or 'force_refresh' (boolean, defaults false), leaving two of three parameters undocumented in both schema and description.

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 plus resource plus scope: 'List the IAM roles granted to you on one account, via that account's SSO portal.' An agent immediately knows this returns the caller's own role grants for a single account, which separates it from explain_role_selection or refresh_accounts. It stops short of explicitly contrasting with any sibling by 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?

There is no when-to-use or when-not-to-use statement and no named alternative. The phrase 'granted to you' and 'SSO portal' hint at the precondition of being logged in, but an agent is left to infer when to call this versus explain_role_selection, refresh_accounts, or cache_status.

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 no annotations, the description carries the burden and does disclose the key non-obvious behavior: an interactive browser approval flow is launched and no other tool will ever do so. It omits whether the call blocks until approval, what happens on timeout/denial, and how long the resulting credentials persist, which are relevant for a stateful auth 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?

Short and front-loaded, with the mechanism and the browser side effect stated first. The second and third sentences restate the same point about browsers not appearing unexpectedly, which is mildly redundant but reinforces an important contract.

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 no prose, and the description covers the critical behaviors an agent needs before invoking an interactive auth flow. The only gap, the org parameter's semantics, is minor for a tool that is optional-parameter and single-purpose.

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 0% and the single 'org' parameter has no description or enum; the prose only says 'to an org' without stating the accepted format or what happens when it is omitted (the schema shows default null). The description adds some meaning by implying the target org scope, but leaves the parameter's optionality and format unspecified.

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 (authenticate) and resource (an org) plus the exact mechanism (SSO device authorization with browser approval). No sibling tool performs authentication, and the phrase 'opens a browser for approval' makes the side effect unmistakable, so an agent can distinguish it immediately.

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 clearly states the trigger condition: queries fail with a message telling you to call this first, and this is the only tool that opens a browser. It does not address adjacent cases an agent might face, such as switching org afterwards (use_org) or checking existing credentials (token_status, org_status), but the core when-to-use guidance is explicit.

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?

No annotations are provided, so the description carries the full burden, but it does disclose the meaningful behavioral detail that results come from the local TOML config rather than a live AWS call. It does not state whether the tool fails when the config is missing, whether the active org is flagged, or whether any authentication is needed.

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 sentence that front-loads the verb and scope with no wasted wording. Nothing is padded or repeated from the name.

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

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

For a zero-parameter read tool with an output schema already defining the return shape, the description supplies the one piece of context an agent needs: the data source. It could add a note about error behavior on a missing config file, but that 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description does correctly avoid implying any filtering or selection input.

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 ('List every org') and names the exact source ('aws-sso-mcp TOML config'), so an agent knows precisely what is returned. It does not distinguish itself from related siblings such as current_org, use_org, or config_show, which is the only thing keeping it from 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 explicit when-to-use or when-not-to-use guidance. The listing verb implies a discovery step before use_org, but the description never says so and never mentions current_org or config_show as alternatives for related questions.

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?

No annotations are supplied, so the description carries the full behavioral burden. 'Report' implies a read-oriented status check, and the output schema likely covers return values, but the description does not clarify whether token validity is checked live or read from cache, whether any permissions are required, or whether the operation has 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?

The description is a single front-loaded sentence with no filler. The parenthetical default behavior is directly useful and does not distract from the core purpose.

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

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

The tool is simple, has an output schema, and the description covers the basic report scope and default org behavior. However, it leaves gaps around sibling selection and org identifier semantics that an agent would need in order to invoke it confidently in 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?

The schema has 0% description coverage for the single optional org parameter. The description adds meaning by explaining that it defaults to the active org, but it does not specify the expected identifier format (name, ID, slug) or how a non-active org should be selected.

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 ('Report') and two concrete resources ('token validity and cache freshness') scoped to an org. It is clear what the tool does, but it does not explicitly distinguish itself from overlapping siblings such as token_status, cache_status, or current_org.

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 context is that the org parameter defaults to the active org. There is no guidance on when to use this tool instead of token_status, cache_status, or current_org, nor any when-not conditions or 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?

With no annotations supplied, the description carries the full burden and does reasonably well: 'report' plus 'for the running server' establishes a read-only snapshot of server-internal counters with no arguments and no mutation implied. It also adds diagnostic context beyond the mechanics by explaining what a high credential-broker or role-cache miss rate indicates, though it does not state whether counters are cumulative since start or reset per 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, each doing distinct work: what is returned, what question it answers, and how to read the numbers. The purpose is front-loaded in the opening clause and there is no filler or 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?

For a zero-parameter read tool with an output schema, the description is nearly sufficient: it explains the data collected and how to interpret two key signals, so return values need not be documented. The remaining gap is routing, since the presence of the sibling cache_status means an agent still has to guess which of the two cache-related tools to call.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The description correctly implies a no-argument call scoped to the running server, matching the empty 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 first sentence gives a specific verb plus resource: report cache hit/miss counts and executor sizing for the running server. It is clear what is measured, but it never distinguishes itself from the sibling tool cache_status, which an agent would plausibly confuse with this one.

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 conveyed indirectly through a scenario ('why was that fan-out slow?') and an implicit alternative ('without turning on debug logging'), which gives an agent a real trigger to reach for this tool. However, there is no explicit statement of when NOT to use it, and the obvious sibling cache_status is never mentioned as an alternative or complement.

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 no annotations, the description carries the full burden. It does disclose that this mutates cached state ('force a refresh') rather than just reading, which is meaningful. But it omits cost/latency (this is likely a network refetch), what happens if both 'org' and 'all_orgs' are supplied, and behavior on partial failure across orgs.

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 resource and the two scoping modes come first. Nothing extraneous to trim.

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 an output schema exists, so return values need not be explained. Still, for an unannotated, zero-description-coverage mutation tool, the description leaves the org/all_orgs interaction and the cost of a 'force' refresh unspecified — both of which affect whether an agent should call it.

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

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

Schema description coverage is 0%, so the description must compensate. It does map the two parameters to intent ('one org, or every configured org'), clarifying that 'org' scopes to a single directory and the alternative covers all configured orgs. However, it never says what 'org' identifies (name vs. id), what the default null means, or how the two flags interact.

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+scope: 'force a refresh of the cached account directory', with the two modes ('one org, or every configured org') made explicit. It is distinguishable from siblings like cache_status or search_accounts, though it never names them directly.

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 only implied: the word 'force' and 'cached' suggest invoking it when the cache is stale, and cache_status is the obvious companion tool, but neither the trigger condition nor the alternative is stated. No when-not guidance, e.g. whether calling it repeatedly is wasteful.

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 no annotations supplied, the description carries the full burden and does well: it discloses that each resolved account runs an independent copy of the whole DAG, that credentials are minted once per account rather than per step, that IAM is the sole authorization boundary, that max_items raises the per-account pagination ceiling, and that nothing is ever evaluated as code. It omits failure semantics — what happens when one step or one account errors, and whether partial results are returned.

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 action, then the step shape, then the reference mechanism, then execution semantics. Every sentence carries information, including the security-relevant 'nothing is ever evaluated as code' clause. Slightly longer than needed only because the steps grammar is inline rather than deferred.

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 no explanation, and the execution model is well covered. But for a 15-parameter, unannotated, inherently multi-step tool, the missing pieces are significant: no error or partial-failure behavior, no guidance on the account-resolution parameters, and no indication of cost or rate limits when fanning out across many accounts.

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 0% across 15 parameters, so the description must compensate. It documents the hardest parameter, steps, in full detail (id, service, operation, params, extract, depends_on, and $ref resolution) and explains max_items, but it is silent on the ten-plus account-selection parameters — org, orgs, role, account_id(s), account_name(s), name_contains, exclude_*, environment, max_accounts — leaving only the phrase 'resolved account' to imply how accounts are targeted.

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 declarative multi-step query DAG across every resolved account, and the opening sentence makes the multi-step DAG nature explicit. The family resemblance to aws_query is signalled but the description never directly contrasts the two, so an agent must infer that this is the multi-step superset.

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 when-to-use guidance and no when-not-to-use. The only sibling reference to aws_query is about the IAM authorization boundary, not about choosing between a single query and a DAG, and nothing says whether this is appropriate for large fan-outs, whether it is expensive, or what to do if a step fails.

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 no annotations, the description carries the full burden and does add real value by disclosing the cache TTL auto-refresh behavior per org. However, it omits whether the operation is read-only, how limit truncation behaves, and what happens when the cache is stale mid-search, leaving meaningful behavioral gaps.

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 short paragraphs, front-loaded with the core action and matching modes, then the cache/consistency note. No filler, though the aws_query equivalence sentence is slightly verbose.

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 explained, and the cache behavior is covered. But for a 6-parameter tool with zero schema coverage, the missing limit/all_orgs semantics and lack of explicit read-only framing leave it only partially complete.

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

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

Schema coverage is 0% across 6 parameters, so the description must compensate. It explains name_contains semantics (case-insensitive substring) and implies name/account_id/org usage, but says nothing about limit, all_orgs, or the org default, leaving half the parameters undocumented.

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 the cached account directory') and enumerates the three matching modes (exact name, substring, account id). It also distinguishes itself from aws_query by noting name_contains behaves identically, so an agent can tell what it targets, though it doesn't fully contrast the two tools' roles.

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 this is a discovery step whose results feed aws_query, which is useful implied guidance, but it never states explicitly when to use this versus aws_query or the sibling refresh_accounts/cache_status tools. Usage is inferable rather than 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?

No annotations are supplied, so the description carries the full burden. It does disclose a genuine behavioral trait — this never launches a browser, so it is a safe non-interactive probe — but it says nothing about whether an invalid token triggers a refresh, what permissions are needed, or any 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?

One short, front-loaded sentence with no wasted words; the capitalized emphasis on the browser-free property aids scanning. Slightly clipped at the cost of missing 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. However, with no annotations and an undocumented org parameter, the definition leaves key calling behavior (scope of the check, invalid-token outcome) unstated for a tool whose whole value is a quick validity verdict.

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

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

The single 'org' parameter has 0% schema description coverage, so the description should explain its meaning and default behavior. It never mentions the parameter at all, leaving unclear whether omitting org checks the current org or all cached orgs.

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

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

Clear verb+resource: 'Check cached SSO token validity'. The 'WITHOUT ever opening a browser' clause implicitly contrasts it with interactive login flows, but it never names a sibling such as login or cache_status to make the distinction explicit.

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 only implied: you check the token when you want to know if your cached session is still good, and the browser-free constraint hints that it is a non-interactive pre-flight check. There is no explicit when-to-use versus login/refresh_accounts, and no statement about what to do if the token is invalid.

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?

No annotations are supplied, so the description carries the burden. It does disclose two important behaviors: the setting is session-scoped and explicit org= overrides take precedence. It omits what happens on an invalid org, whether it affects credentials/tokens, and whether the change is reversible.

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 waste. The trailing parenthetical is terse to the point of being slightly cryptic, but it is not 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?

For a one-parameter session setter with an output schema, the core action is covered, and return values need not be explained. Missing pieces are the valid value source, session lifetime, persistence, and failure behavior, which matter for a stateful setter with no annotations.

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

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

There is one required parameter, org, with 0% schema description coverage, so the description is the only source of meaning. It only implies the value can also be supplied one-off as org= and never states whether it is a name, ID, or alias, nor where to discover valid values (orgs_list).

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 plus resource: 'Set the active org for this session.' This clearly separates it from read-only siblings like current_org and orgs_list. It does not name a sibling explicitly, but the action is unambiguous.

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

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

The parenthetical 'one-off org= overrides still win' tells the agent that a per-call override takes precedence, which is real routing guidance. However, it never says when to prefer this over login, current_org, or orgs_list, or whether the change persists beyond the session.

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