Argus API Spend

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

With no annotations, the description carries the burden well: it discloses that the credential is validated against the provider BEFORE storing, stored encrypted, and that an initial sync is queued afterward. This conveys the mutation's side effects, though it omits auth/permission needs and any rate limits.

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 action and side effects are front-loaded, and the args block is information-dense rather than padded. The single run-on args sentence is slightly dense but every clause adds 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?

For a 5-param mutation with a nested object and no annotations or output schema, the description covers the operation, side effects, and conditional meta requirements. Only minor gaps remain (credential_type values, return value, though output schema 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 coverage is 0%, so the description must compensate, and it does: it explains provider (id source), secret, credential_type, label, and meta, including provider-specific meta requirements (OpenRouter admin_key {tracked_key}, Cloudflare {account_id}/{billing_day}). It doesn't specify credential_type's allowed values, leaving a small 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 (connect) and resource (provider) tied to 'THIS project' with a credential, and points to list_available_providers for the id. This clearly separates it from siblings like create_connect_link and sync_connection.

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 clearly implied (connect a provider using an id from list_available_providers) and it explicitly restricts secrets to operator-provided keys. It doesn't explicitly contrast against create_connect_link or sync_connection, but the context is clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the returned URL is single-use and valid for 1 hour, that the secret never transits the agent, and that the result must be polled via get_connect_link. It omits what happens on expiry or whether a new link must be minted, which keeps it 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?

Front-loads the core mechanism and the safety rationale before the workflow and arg list; every sentence is load-bearing. The inline 'Args:' tail is slightly terse and denser than the prose above it, but it compensates for the empty 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?

No annotations and no output schema, so the description must cover behavior and it does: link lifetime, single-use semantics, operator handoff, and the follow-up poll. The remaining gap is parameter meaning for credential_type and label, which nothing else in the definition supplies.

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 trailing arg list does real work: provider is tied to list_available_providers, and credential_type/label are marked optional. However, credential_type and label are given no meaning beyond optionality, leaving the agent to guess valid values or label conventions.

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: it hands a provider credential to Argus via a single-use URL rather than passing the secret through the agent. The mechanism (URL, 1-hour validity, operator pastes key) makes it unambiguously distinct from connect_provider.

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 connect_provider whenever you don't already hold the secret.' It also describes the downstream workflow — show the URL to the operator, then poll get_connect_link for the connection id — so both the selection condition and the next step are 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 provided, so the description carries the full behavioral burden. It discloses the advisory categories returned, which is useful, but says nothing about freshness guarantees beyond 'current', ordering, volume limits, or what an advisory entry contains. For a tool with zero annotation coverage this is thin.

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 resource stated first and the categories parenthetically enumerated. Every clause earns its place; nothing is padded.

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 trivial no-argument listing tool this is roughly adequate, but with no output schema the return shape and the meaning of each advisory type remain undocumented. One more sentence on what an advisory contains or how to act on it would close the 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 the baseline of 4 applies. There is no parameter semantics to explain and the description correctly does not invent any.

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 ('All current advisories') and enumerates the advisory categories (top-up, upgrade, near-limit, spend-spike), which makes the scope concrete. It does not explicitly differentiate itself from siblings like get_overview or get_rate_limit_status, but the resource is distinct enough to be identifiable.

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, and no mention of alternatives such as get_rate_limit_status or get_overview. The agent must infer that this is the advisory-feed tool 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?

No annotations are supplied, so the description carries the full burden. It does add real behavioral context by disclosing the terminal/exceptional states, notably 'locked after repeated bad credentials', which tells the agent about lockout semantics. It omits that this is a pure read, what happens with an unknown or malformed id, and any auth or rate-limit constraints.

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 compact sentence with the returned states front-loaded and no filler. The fragment style is efficient, though the missing subject ('Returns the status of...') slightly weakens the opening.

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 status enumeration usefully describes the effective return values, which is the strongest part of the definition. But for a lookup tool with no annotations, the meaning of the required 'id' and the usage context are left unaddressed, so it is 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 description coverage is 0% and the single required parameter 'id' is a bare string with no explanation. The description never clarifies whether 'id' is the connect-link id, a provider id, or a token, so it fails to compensate for the schema gap on the one parameter that matters.

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 the resource (a connect link) and the exact thing returned (its status), and it enumerates the status values including 'done (with connection_id)'. That is specific enough to distinguish it from connect_provider, create_connect_link and list_connections, though it never explicitly contrasts with those 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?

There is no statement of when to call this versus create_connect_link (to obtain a link) or list_connections (to enumerate them), and no polling or prerequisite guidance. The status list hints that this is a progress-check, but the agent has to infer that entirely.

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 the semantic meaning of each state, that 'unreconciled' means no provider anchor has been compared yet, and a real coverage limitation (OpenRouter accounting covers only calls via the connected key). It stops short of stating read-only nature or any permission/prerequisite, which is a modest gap for a zero-param 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?

Two dense sentences, front-loaded with the core purpose and followed by qualifiers. Every clause carries information, though the term 'Argus's itemized total' introduces project-specific jargon without explanation.

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 or annotations exist, so the description must explain return semantics and it does: states, drift %, and the meaning/limits of 'unreconciled'. It doesn't enumerate return fields (e.g., drift field name, provider list) or explain 'Argus', so it is strong but not 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The mention of spend_basis qualifying mtdSpendUsd refers to output fields rather than inputs, so it doesn't add 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?

Opens with a specific verb+resource pair ('Cost-accuracy state per provider') and enumerates the three possible states (exact, estimated, unreconciled) plus the drift metric. This distinguishes it from get_request_costs or get_overview, though it never explicitly names those siblings as 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 implied rather than stated: the agent can infer it should call this when it needs to know whether spend numbers are trustworthy. The 'unreconciled' definition and the caveat about OpenRouter covering only calls through the connected key are useful qualifiers, but there is no explicit when-to-use/when-not or named alternative.

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 at all, the description carries the full burden, and it does disclose genuinely non-obvious data-quality behavior: spend may be missing before observed_since, and balance may cover the account, a single key, or be unknown. It omits freshness/latency expectations and whether connections must exist first, keeping it from 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, front-loaded with the metric list, and every clause carries information. The second sentence is dense with nested parentheticals and quoted enum-like values, which hurts scanability slightly, 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?

With no output schema and no annotations, the description must explain return values and largely does, decoding the two most important fields. Gaps remain: no mention of what happens with zero connected providers, data freshness, or call cost for a cross-provider aggregation.

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 zero input parameters, so the baseline is 4. The description's explanation of spend_basis and balance_scope concerns response fields, not inputs, so it adds no input-side meaning but also has nothing to get wrong.

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 the resource precisely ('cross-provider rollup') and enumerates the metrics returned: balance, burn rate, days-to-zero, month-to-date spend, projection, rate-limit headroom. 'Cross-provider' implicitly distinguishes it from get_provider and get_request_costs, though no sibling is named 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?

Use is only implied by 'cross-provider rollup' — an agent can infer this is the aggregated view versus per-provider tools like get_provider. There is no explicit when-to-use/when-not statement or reference to alternatives, so the agent must infer the selection rule.

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 load, and it does disclose the return-side vocabulary: spend_basis ('reported' | 'observed_since_connected'), observed_since, and balance_scope ('account' | 'key' | 'unknown'). However, it says nothing about whether this is a read-only snapshot, whether it triggers a live upstream fetch (latency/quota implications), or what happens for an unknown connection id.

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, and the scope ('one connection id') is front-loaded before the return-field enumeration. Slightly dense parentheticals but each 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?

There is no output schema, so the description must fully describe returns, and 'Full metrics' is left completely undefined while only three auxiliary fields are enumerated. For a single-connection read tool with no annotations, it should say what the metrics comprise and what failure modes look like.

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 is the only source, and it does usefully clarify that the lone parameter is a connection id rather than a provider id — non-obvious given the tool name get_provider. It still doesn't explain where to obtain a connectionId (list_connections) or whether stale/disconnected ids are accepted.

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: it returns full metrics plus rate-limit snapshots scoped to a single connection id. This is clear enough to distinguish it from bulk list tools, but it never names the closest siblings (get_rate_limit_status, get_overview, get_request_costs), so an agent must guess which of the overlapping metric tools 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?

There is no when-to-use guidance at all: no statement of prerequisites (must the connection be connected first via connect_provider?), no exclusions, and no pointer to the overlapping siblings. The only implicit signal is that it operates on one existing connection.

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 at all, the description carries the full burden of behavioral disclosure. 'Latest' hints at recency but the description says nothing about how fresh the data is, whether it is cached/polled, whether it requires provider credentials, or how partial provider outages affect 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 tight sentence with the two returned metrics front-loaded and no filler. It is efficient, though it is arguably too terse to be maximally useful.

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-argument status tool with no output schema, the description does state the returned fields, which is the minimum an agent needs. However, with no annotations and no return schema, it should say more about freshness, per-provider granularity, and failure behavior to be fully self-sufficient.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline for an argument-free call is 4. The description correctly implies no input is needed.

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?

Names a specific resource (rate-limit headroom and error rate) and its scope (across the org's providers), which is concrete enough to distinguish it from cost or overview siblings. It never explicitly contrasts itself with those siblings, so it stops 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 guidance on when to call this versus get_overview, get_cost_accuracy, or get_advisories. Usage is only implied by the tool name; no conditions, prerequisites, or exclusions are 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?

With no annotations, the description carries the full burden, and it does disclose the shape of returned items (model, tokens, USD cost, provenance), which is genuine behavioral content. But it omits what 'recent' means (time window), auth requirements, ordering, and any rate-limit context.

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?

Compact and front-loaded: purpose first, then a terse Args list. No filler, though the parenthetical field list and args sentence could be split for readability.

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 must (and does) sketch the returned fields, and it documents the undocumented limit default/max. However, it lacks the when-to-use routing and the freshness semantics ('recent') an agent needs for a cost-reporting tool with several overlapping 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 only 50% (limit has no schema description), and the description compensates by stating limit's default of 25 and max of 100, which are not present in the schema. provider is only echoed from the schema's own example, so the gain is partial but real.

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: returns itemized per-request costs for a provider, and lists the fields returned (model, tokens, cost, provenance). This distinguishes it from siblings like get_cost_accuracy and get_overview, though it never names an alternative 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?

No guidance on when to use this versus get_cost_accuracy, get_overview, or get_provider. It only lists args, leaving the choice of tool entirely 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?

No annotations, so the description carries the full burden. It usefully discloses the architectural distinction between the poll plane and the telemetry plane, which is real context beyond the name, but it says nothing about return shape, ordering, or whether 'available' accounts for already-connected providers.

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 sentences, zero filler, with the primary scope stated first and the exclusion plus documentation pointer second. Nothing could be removed without losing information.

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

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

For a zero-parameter, no-output-schema lister, the description conveys what set is returned and what falls outside it, which is enough to invoke it correctly. A word on how the result feeds connect_provider would have made it 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?

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter detail is 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 the resource and its scope precisely: providers connectable with an API key, in the 'poll plane'. The listing verb is only implied by the tool name rather than in the description, and the sibling connect_provider is never named, so differentiation is left partly 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?

The description supplies a data-scope boundary -- API-key providers here, everything else via telemetry ingest docs -- which tells the agent this list is not exhaustive. It never states when to call this rather than list_connections or connect_provider, so tool selection remains 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?

No annotations are provided, so the description carries the full burden. 'List' implies a safe read and 'the org's' hints at org scoping, but nothing states permissions, whether results are paginated, or what 'status' values mean. For a zero-annotation tool this is thin.

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 efficient sentence with the resource and the useful return attribute front-loaded. 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?

With zero parameters and no output schema, the description is roughly sufficient to invoke the tool, but it leaves the return shape ('status' values) and any auth requirements uncovered.

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 no parameters, so the baseline of 4 applies. There is no parameter syntax or format for the description to clarify.

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 clear verb+resource (list connected providers) and adds the returned attribute (status). It implicitly contrasts with list_available_providers by specifying 'connected', but never names or rules out that sibling 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 when-to-use, when-not-to-use, or alternative-routing guidance. An agent must infer from the name alone that this is for auditing existing connections rather than discovering new ones.

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; 'Queue' usefully signals asynchronous, non-blocking behavior rather than a synchronous fetch. However, it omits whether repeated calls are safe, whether it is rate-limited (notable given the get_rate_limit_status sibling), and whether it requires authorization.

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, front-loaded sentences with the action stated first. The trailing 'Args: connection_id.' duplicates the schema and is the one low-value fragment.

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 trigger tool with no annotations and no output schema, the description covers the core action reasonably. It still leaves open what the queue actually returns, whether side effects are incurred, and how to obtain a valid connection_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% for the single parameter, so the description must compensate and it only does so minimally by naming the argument. It does not explain the ID format or that connection_id comes from list_connections, leaving the agent to infer the source.

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 ('Queue ... refresh') and the resource scope ('for one connection'), and the 'balance/usage/plan' detail clarifies what is refreshed. It does not explicitly contrast with siblings like list_connections or get_rate_limit_status, 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?

'Immediate' hints that this is an on-demand alternative to scheduled refreshes, but the description never states when an agent should call this versus list_connections or get_overview, nor any prerequisites. Usage must be inferred 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.