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

Explicitly reconciles the readOnlyHint=false annotation ('It is not marked read-only only because tf_dir runs terraform plan there, which executes that directory's provider plugins'), which is exactly the context an agent needs. It also documents the three verdicts (allow/escalate/block), their semantics, the env knobs, and that it never executes anything.

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-loads the core verdict and uses scannable bullets for allow/escalate/block, but repeats the advisory/propose-only message several times ('ADVICE ONLY', 'propose-only guardrail', 'nable does not auto-execute'), which is mild redundancy.

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

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

With no output schema, the description usefully defines the return verdicts and their meanings, and it explains the annotation quirk. It falls short on clarifying the four non-cost parameters, which an agent would need before calling with anything beyond the required action_type.

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 description must compensate. It explains action_type with concrete value examples and groups tf_dir/helm_diff/monthly_delta_usd as the three cost-related inputs, but leaves budget_name, terraform_plan_file, and terraform_plan_json entirely unexplained and doesn't map each cost option to its specific parameter.

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

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

States a specific verb and resource ('Advisory policy gate: should a proposed remediation action proceed?') and immediately frames the scope as propose-only. An agent can distinguish this from estimate_change_cost or get_cost_summary because it's framed as a policy verdict, not a cost estimate.

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 triggers ('can the agent do X', 'is this action within policy', 'should I apply this fix') plus examples, which strongly signals when to call it. It does not name sibling tools or state when NOT to use it, keeping it below a 5.

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

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

Annotations already declare read-only/idempotent/non-destructive; the description goes further by declaring 'Advice only, it never blocks' — a critical behavioral trait no annotation conveys — and by pre-describing the return payload (verdict, reason, recommendation, headroom). It also discloses that session_id resolves to the calling session, removing a silent-default surprise.

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 one-line purpose, then progressively more detail; each sentence carries distinct information (timing, return shape, non-blocking nature, param usage). The opening rhetorical question is slightly padded but functions as a memorable framing line.

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

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

No output schema exists, yet the description enumerates the return fields (verdict states, reason, recommendation, headroom) and explains the cap semantics, so an agent knows what comes back without probing. Only two optional params and both are addressed, making this complete for its complexity.

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 parameter load, and it largely does: estimated_next_tokens is given a concrete purpose and session_id is explained as defaulting to the calling session. What's missing is any guidance on magnitude/units for estimated_next_tokens or when to override session_id.

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 plus resource ('check ... AI budget') in the first line and pins the scope to this session's cap and the monthly budget. That scope distinguishes it from cost-oriented siblings such as get_cost_summary and estimate_change_cost, which concern cloud spend rather than agent token budget.

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?

Explicit invocation timing: 'Call this before an expensive run,' plus a conditional use for estimated_next_tokens ('to test whether the next task would tip a token budget over'). It also sets expectations on what to do with the result ('relay the verdict and let the human decide'), but never names a sibling or says when not to call 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?

Adds real context beyond annotations: propose-then-confirm, credentials never leave the machine, STS verification, and a no-arg discovery pass that stores nothing. It explicitly reassures 'never creates, modifies, or deletes anything in your AWS account', which is consistent with destructiveHint=false while readOnlyHint=false correctly reflects that a connection is persisted. It doesn't say what 'connected' unlocks or whether re-connecting replaces an existing connection.

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 action, then constraints, then examples. The example utterances are mildly redundant given the prose above them, but every paragraph still carries information an agent would otherwise lack.

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-optional-parameter connection tool with no output schema, the description covers the call sequence, side effects, safety profile, and credential handling — enough for an agent to invoke it correctly on the first try.

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% (account_id has no description), so the description must carry the meaning — and it does: omit account_id to list available accounts, set it to the chosen identifier to connect. It doesn't state the identifier's format (account number vs profile name), which is the remaining gap.

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 ('Connect an AWS account') and immediately scopes it: reads existing local credentials, verifies them against STS, connects the chosen one. This clearly separates it from connect_azure and connect_gcp, which are the only plausibly confusable siblings.

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

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

Gives an explicit two-call workflow: no arguments first to enumerate accounts (nothing stored), then a second call with account_id. That is exactly the sequencing an agent needs. It stops short of naming alternatives or exclusions (e.g. when to prefer connect_gcp or list_connected_providers instead), so not a 5.

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

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

The description is rich about security behavior and the expected user flow, but it presents the tool as returning a script for the user to run later, which implies a read-only informational operation. The annotations declare readOnlyHint=false, meaning the tool is not read-only, so the description contradicts the structured behavioral hint.

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

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

The description is front-loaded with the key constraint (keeping the secret off the model) and then explains the why and the flow. It is somewhat verbose but every part supports the unusual security model, and the examples are compact.

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

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

There is no output schema, so the description appropriately explains that the tool returns a Cloud Shell script and that the user must finish with `finops setup azure`. That is enough for an agent to route the user correctly, though it could mention prerequisites or what the script contains.

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 has zero parameters, so the description does not need to explain parameter semantics. The baseline for no parameters applies, and nothing in the description 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 states a specific purpose: guiding Azure connection while keeping the service-principal secret off the model, and it explicitly distinguishes this flow from connect_aws and connect_gcp. It also says the tool returns a Cloud Shell script for the user to finish in their own terminal, so the tool's role is clear.

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 names the alternatives connect_aws and connect_gcp and explains why they are different: those read local credentials, while Azure requires a client secret that must not be pasted into the model. The examples further reinforce when to use it (connecting Azure or asking how to connect an Azure subscription).

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 substantial context beyond the annotations: propose-then-confirm two-phase flow, the exact credential sources it reads, that credentials stay on the machine, and that it never changes anything in GCP. This reconciles the seemingly odd readOnlyHint=false — the write is a local connection record, not a GCP mutation — so there is no annotation contradiction.

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

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

Front-loaded with the core action and the two-step flow before any examples; every sentence carries real information. The trailing example phrasings are mildly redundant with the prose but plausibly useful for matching user intent, so the cost is small.

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

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

No output schema exists, and the description partially compensates by saying the no-arg call returns the visible open billing accounts. It does not describe what the connect call returns or what happens on failure (no credentials, multiple/zero accounts), which would matter for a 0-required-param setup 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 0% and billing_account_id has no description at all, so the description must carry the load — it does, explaining that omitting it lists accounts and setting it selects the one to connect. The only gap is the expected ID format (e.g. 0X0X0X-XXXXXX-XXXXXX), which an agent must infer from the listing output.

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 ('Connect a Google Cloud billing account') plus the scope of what it touches (existing local credentials, open billing accounts). The provider-specific wording lets an agent distinguish it from connect_aws and connect_azure without opening any schema.

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

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

Gives explicit procedural guidance: call with no arguments to list accounts (nothing stored), then call again with billing_account_id set to connect one. It also states the prerequisite — credentials must already exist via GOOGLE_APPLICATION_CREDENTIALS or gcloud ADC — and supplies example user phrasings.

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?

Directly reconciles with the annotations: it explains that it never mutates anything and that readOnlyHint=false exists only because tf_dir triggers `terraform plan` and its provider plugins. It also discloses the verdict vocabulary (ok/warn/over_budget/no_budget) and the no-budget fallback behavior — context the annotations cannot convey.

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 verdict, then the safety caveat, then the input routes and triggers. Slightly repetitive ('cost preflight' restated in triggers and examples), but every section carries usable signal.

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

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

No output schema exists, and the description compensates by naming the primary return fields: machine verdict, monthly and annual cost delta, and budget headroom. Combined with the mutation disclaimer, an agent has everything needed to call it and interpret the result.

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%, yet the description documents all six parameters meaningfully: it groups terraform_plan_json/terraform_plan_file/tf_dir/helm_diff as alternative ways to describe the change, explains monthly_delta_usd as an escape hatch with a concrete example, and explains budget_name's default and the no-budget outcome. The only gap is precedence when multiple inputs are supplied.

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 ('Cost preflight for a proposed change') and immediately names the scope: estimates and checks budget fit but never applies anything. The distinction from siblings such as get_cost_summary and check_ai_budget is clear from the 'proposed change before apply' framing.

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?

Explicit timing guidance: 'Call this BEFORE applying an infrastructure change', plus good triggers ('will this fit my budget', 'cost preflight'). It names input routes and an escape hatch, but never explicitly contrasts itself with the sibling cost/budget tools, so the when-not-this-tool case is left implicit.

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 read-only, idempotent, non-destructive, and open-world behavior. The description adds the aggregation dimensions and example queries, but omits permissions, data freshness, currency, and response 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?

The description is brief and front-loaded with the core behavior. The examples are short and earn their place by illustrating realistic usage.

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 six undocumented optional parameters and no output schema, the description does not provide enough detail for an agent to use the filters correctly. It is sufficient for a broad summary call but incomplete for parameterized cost queries.

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 are six optional parameters with 0% schema description coverage. The description mentions account and examples imply dates and provider, but it does not explain account/category/provider formats, date syntax, or valid granularity values.

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: get total spend summarized by service, account, and region. It is clear what the tool returns, but it does not explicitly distinguish itself from siblings such as estimate_change_cost.

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 examples clearly show when to use the tool, such as asking about last month's spend or an AWS cost summary for January. There are no explicit exclusions or named alternatives, but the usage context is concrete.

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, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description goes beyond them by describing the response contents — every provider appears, tagged connected or not-configured, not-configured rows carry the setup command to run, and the active plan is included.

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

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

The core sentence is front-loaded and answers what/why in one line, with the examples and setup-command detail following as supporting color. The two example phrasings are mildly redundant with the prose, keeping it just short of maximally tight.

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

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

With no parameters and no output schema, the description carries the return-value burden itself and does so: it says every known provider is listed, how each is tagged, what the not-configured entries contain, and that the active plan is included. An agent needs nothing else to call it or interpret the result.

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 and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter semantics are needed or missing.

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 every cloud, SaaS, and LLM provider) plus the exact per-entry payload (connected / not-configured, active plan). This distinguishes it from the connect_* siblings, which perform configuration rather than enumeration.

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 starting point for 'what am I connected to' and for spotting which connector still needs credentials" gives a clear use context, reinforced by two example utterances. It never explicitly says to use connect_aws or nable_setup_status instead for other tasks, so the alternative routing is only implied.

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

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

Beyond annotations declaring readOnly, idempotent, open-world, and non-destructive behavior, the description adds critical operational rules: never ask for secrets in chat, prefer ambient credentials, and hand off terminal commands for paste-a-key providers. These are meaningful behavioral constraints an agent could not infer from 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 front-loaded with purpose and usage, followed by actionable hard rules and examples. It is somewhat long, but the security and handoff rules justify the length; minor redundancy appears in framing the rules.

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

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

With no output schema and no parameters, the description carries the burden well by explaining what the status includes (connected providers, local credentials, exact commands) and how to act on it safely. It provides enough context for correct invocation.

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

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

The tool takes zero parameters, so parameter semantics are inherently minimal. The schema already indicates an empty object, and the description does not need to explain 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 clearly states an onboarding/status purpose: what is connected, what credentials are present, and the exact command to connect remaining providers. It is specific about the resource and output, though it does not explicitly distinguish itself from the sibling list_connected_providers 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 explicit triggers (user asks to connect a provider, setup is incomplete, asks what is missing) and examples. It also names preferred zero-secret paths such as `finops connect` and `finops setup gcp`, so an agent knows when and how to use this tool versus direct connection paths.

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 read-only, idempotent, non-destructive, and open-world. The description adds useful behavioral context: results are tailored to connected accounts and include underlying tool names only when detailed=True.

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

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

The main purpose and usage guidance are front-loaded, and the example phrases are helpful. The repeated examples are slightly redundant, but they reinforce the trigger conditions without obscuring the call semantics.

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 in detail. The description covers purpose, invocation timing, and the only parameter, making it complete enough for an agent to call correctly.

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

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

Schema description coverage is 0%, but the single parameter is explained in the description: detailed=True lists underlying tool names. That compensates for the schema gap, though it does not describe the default false behavior explicitly 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 capability-discovery function and makes its scope clear: it shows everything nable can do, tailored to connected accounts. This is distinguishable from sibling tools such as cost summaries, provider connections, and policy checks.

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

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

It gives explicit trigger phrases, states when to call it after a user connects their first account, and explains the detailed flag. Alternatives are implicit because this is the dedicated capability-discovery tool among operational siblings.

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