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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered structurally. The description adds nothing beyond that: no note on what an action contains, whether the record can be missing, how errors surface, or whether the call has side effects or remote latency implications.

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 that is front-loaded and free of padding, but its brevity comes from omission rather than discipline. The parenthetical endpoint is arguably the only sentence with real informational content.

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 should describe what a returned action looks like or what fields matter; it does not. For a fetch-by-id tool with an undefined resource name, an agent lacks the context needed to use the result meaningfully.

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 carries the full burden for the single id parameter. The path template '(GET /v1/actions/{id})' does imply id is a path identifier, but it says nothing about format, where the id comes from (presumably actions_list), or validation behavior.

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 pairs a verb and resource ('Get an action') and adds the underlying endpoint (GET /v1/actions/{id}), which confirms it is a single-record fetch rather than a list. However, 'action' is never defined, so an agent cannot tell what domain object is being retrieved, and there is no explicit contrast with the sibling actions_list.

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

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

No when-to-use guidance is given. The implied distinction from actions_list (single item vs collection) must be inferred entirely from the verb, and there are no stated prerequisites, exclusions, or alternative tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and reach are covered. Beyond that the description only echoes the HTTP method and endpoint; it says nothing about default page size, pagination, ordering, or what happens when status/clientId/parentId are omitted. For a list endpoint where defaults drive the result set, that is a meaningful gap.

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

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

The description is short and front-loaded, which is good, but its single informative clause duplicates the schema and the title, and it still leaves the tool underspecified. Brevity here reflects thinness rather than disciplined editing.

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 four optional parameters, 25% schema coverage, and no output schema, the description carries the burden of explaining filter semantics and return shape and fails to do so. An agent cannot tell what a default call returns or how clientId and parentId narrow the results.

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 only 25%, so the description needs to compensate for clientId, parentId, and limit — it does not. The one note it offers ("status is comma-separated") is already stated verbatim in the schema for the status property, so it adds no meaning beyond structured data.

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

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

"List actions" names a specific verb and resource, and the GET endpoint confirms it is a read/list operation. However, it does nothing to distinguish it from the sibling actions_get, and the parenthetical mostly restates the title. An agent knows roughly what it does but not how it differs from the individual-action fetch 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?

There is no statement of when to use this tool versus actions_get or other list tools such as audit_list or alerts_list. No prerequisites, no exclusions, and no indication of what the listing is scoped to (workspace, client, parent).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the REST path (GET /v1/ad-accounts/{id}), which restates the read nature rather than adding context such as auth requirements, error behavior for unknown ids, or whether the response includes synced metrics.

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 sentence, front-loaded with the action, with the endpoint in parentheses as secondary detail. Nothing is wasted, though the brevity borders on under-specification rather than tightness.

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

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

For a single-parameter read tool this is close to minimally adequate: an agent knows to pass an id and expects one account back. With no output schema and no schema descriptions, the agent still lacks the id format and any notion of what the returned object contains, which the description could have supplied in one clause.

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 property 'id' is a bare string with no documentation. The description only shows '{id}' embedded in the endpoint path, hinting that it is a path parameter, but says nothing about format (numeric vs. platform-prefixed) or where the agent obtains a valid 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?

The description names a specific verb and resource ('Get one ad account'), and the singular 'one' implicitly separates it from sibling adAccounts_list, which returns many. It stops short of naming adAccounts_list or adAccounts_manage explicitly, so the differentiation is inferable rather than stated.

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

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

There is no when-to-use guidance beyond the implicit need to already hold an account id. Nothing tells the agent when to prefer adAccounts_list (discovery), adAccounts_manage (mutation), or adAccounts_sync (refresh), all of which appear in the sibling list.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-facing behavior are covered. Beyond that the description only repeats the HTTP endpoint (GET /v1/ad-accounts) and says nothing about pagination, result ordering, or what a listing contains, despite there being no output schema.

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

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

A single short sentence with no filler and the filter dimensions front-loaded after the verb. It is efficient, but the brevity comes at the cost of substance rather than being tight-but-complete.

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

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

For a simple read-only list tool this is thin: no output schema exists, so the description should at minimum indicate the returned shape and pagination behavior, and it should say how this differs from adAccounts_get/manage/sync. None of that is present, leaving the agent with little more than the tool name.

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 carries the full burden. It maps the two parameters at a name level (connectionId filters by connection, managed filters by managed flag) but never explains what a 'connection' is, what 'managed' means for an ad account, or that the values are the strings 'true'/'false' rather than booleans.

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 verb and resource ('List ad accounts') and names the two filter dimensions, so the basic purpose is clear. However, it is nearly a verbatim restatement of the title and gives no differentiation from nearby siblings such as adAccounts_get, adAccounts_manage, or adAccounts_sync, which an agent must distinguish before choosing this 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?

The word 'optionally' hints that both parameters can be omitted, but there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives like adAccounts_get for a single account or adAccounts_sync for refreshing data. The agent is left to infer routing entirely from tool names.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), it discloses the important trait that nothing is sent without confirm: true and that there is no server-side dry run — a genuine behavioral fact the annotations do not convey. It stops short of describing permission requirements or reversibility of the assignment.

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 action, then the critical safety constraint and endpoint. No filler 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 write tool with no output schema but with a confirm-gated preview flow documented in the schema, this covers the essentials an agent needs to call it safely. Missing only permission/error context and clarification of the untouched body fields.

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 50%: confirm and idempotencyKey are already documented in-schema, while id, body.clientId and body.managed are bare. The description maps 'clientId' to 'client' and 'managed' to the managed flag, adding marginal meaning, but says nothing about what id refers to or any constraints on the nested body.

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 ('Assign an ad account to a client') plus the second effect ('set whether Advernue manages it') and even gives the PATCH endpoint. It is clearly distinguishable from adAccounts_list/get/sync siblings, though it never names them 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?

The description gives a gating condition (must pass confirm: true) which is operational guidance, but it offers no when-to-use vs when-not guidance relative to siblings like adAccounts_sync or adAccounts_get. Usage is implied from the verb rather than spelled out.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the description's real contribution is the confirmation contract: nothing is executed without confirm=true and there is no server-side dry run, which tells the agent the preview is mandatory. It stops short of saying what data is overwritten, whether the sync is destructive to existing entities, or whether the call is long-running/rate-limited.

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 compact sentences, with the write/confirm warning placed prominently at the end where it is hard to miss. 'Now' and the endpoint parenthetical are slightly redundant with the title but still earn their space as routing cues.

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 three-parameter write tool with no output schema and open-world behavior, the definition covers the safety gate but says nothing about what gets synced (which entities, what time window), what the preview response contains, or how errors surface. The essentials for calling it safely are present; the essentials for predicting its effects are not.

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 67%: confirm and idempotencyKey are already documented in the schema, and the description only adds that adAccountId appears in the request path. It contributes little meaning beyond what the structured fields already provide.

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 (sync) and resource (entities and metrics for an ad account) plus the underlying endpoint POST /v1/sync/{adAccountId}, which lets an agent separate it from adAccounts_get/list/manage. It does not, however, distinguish it from adjacent sync-style siblings such as audiences_sync or connections_importMetrics.

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 word 'now' implies an on-demand pull, and the confirm gate signals this is a deliberate write action, but there is no explicit statement of when to choose this over adAccounts_manage or the other sync tools. The agent must infer the usage context.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true; the description adds real behavioral context the annotations do not: the entity is created paused unless status is supplied, and the call is a dry run unless confirm=true. That default-paused and preview-by-default behavior is exactly the kind of pre-call surprise worth disclosing. It stops short of covering idempotency behavior or permission requirements.

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

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

Two tightly packed sentences with the action and the write protocol front-loaded, and no filler. Minor cost: stacked parentheticals and a phrase lifted almost verbatim from the title make it slightly denser than it needs to be.

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

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

For a write tool with a deeply nested body (Bid/Money/Budget/Targeting) and no output schema, the description covers creation semantics and the dry-run gate but says nothing about what comes back (e.g., the new ad group ID) or how to recover it. Adequate to avoid a wrong call on safety, thin on the result side.

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 67%, so the schema already documents confirm and idempotencyKey. The description adds meaning only for the status field ('created paused unless status is given'); it says nothing about campaignId, targeting, bid, or budget semantics, so it does not meaningfully beat the baseline.

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

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

States a specific verb and resource ('Create an ad group') plus the parent scope ('under a campaign') and the backing endpoint (POST /v1/ad-groups). This clearly separates it from adGroups_list and adGroups_update in the sibling set.

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 tells the agent the execution protocol (dry run by default, set confirm: true to actually write), which is genuine usage guidance for the call itself. However, it never says when to reach for this versus adGroups_update or campaigns_create, nor what prerequisites exist (campaign must exist, targeting required).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered structurally. The only added context is the REST endpoint 'GET /v1/ad-groups', which tells the agent nothing about pagination, result size, default ordering, or whether filters are ANDed. For a list tool whose output shape is undocumented, that 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 sentence with no wasted words and the endpoint front-loaded, so structure is fine. However the brevity is under-specification rather than discipline; there is no second sentence carrying the filtering or return-value context an agent needs.

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

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

Two optional filters with no output schema and no parameter descriptions mean the description should explain what is returned and how the filters combine, and it does neither. Against a many-sibling tool family, this leaves the agent guessing at default behavior.

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 description mentions neither 'status' nor 'campaignId'. The enum values under EntityStatus are the only hint, and the description does not compensate for the coverage gap, so meaning beyond the raw schema is essentially absent.

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 verb and resource: 'List ad groups'. That is enough to separate it from adGroups_create, adGroups_update and ads_list without opening schemas. It stops short of stating scope (all ad groups vs. filtered), so it is clear but not distinctive.

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 call this versus adGroups_create/adGroups_update or ads_list, and no mention of whether the filters are optional narrowing or required context. The agent must infer that this is the read/discovery entry point from the name alone.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true; the description adds the genuinely non-obvious fact that calls are dry-run unless confirm:true is passed, which prevents accidental live mutations. It stops short of saying whether omitted body fields are preserved (PATCH merge) or cleared, and what the dry-run preview returns.

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, front-loaded with the action and the write-safety caveat, with no filler. The opening phrase duplicates the tool title verbatim, which is minor waste but not harmful.

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 mutation tool with a deeply nested body (bid strategies, budget types, targeting arrays) and no output schema, the description covers the safety mechanism but not update semantics, validation behavior, or what a dry-run returns. Adequate but leaves real gaps an agent would need to guess at.

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 50%: confirm and idempotencyKey are documented in the schema itself, while id and body are not. The description lists the body fields (name, status, budget, targeting, bid) but only mirrors the schema's property names without adding format, currency/micros semantics, or partial-update behavior. Baseline 3 is appropriate.

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

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

States a specific verb and resource ("Update an ad group") plus the concrete mutable fields and the underlying PATCH route, so the agent knows exactly what is being modified. It does not distinguish itself from siblings such as adGroups_create or campaigns_update, leaving that to the tool name alone.

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 gives clear execution guidance (dry run by default; confirm: true to execute), which is the most common failure mode for write tools. However, it offers no guidance on when to choose this over adGroups_create or campaign-level updates, and no prerequisites or exclusions.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true; the description supplies far more: the created entity defaults to paused, execution is a dry run unless confirm: true is set, and the underlying write endpoint is named. It stops short of mentioning permissions, rate limits, or what the dry-run preview returns.

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 with zero filler; the resource, the default paused state, and the dry-run safety gate are all front-loaded before the endpoint citation.

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 mutation tool with a nested body, no output schema, and only 3 parameters, this covers the essentials an agent needs: what it creates, under what parent, and the dry-run-to-execute safety step. It lacks detail on the return payload and required body fields, but the schema carries those.

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 67% and the description adds essentially nothing beyond the schema—the 'created paused unless status is given' note duplicates the schema's status description. Body fields such as adGroupId, name, creativeId and destinationUrl are left to the nested schema, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Create an ad under an ad group'), adds the key behavioral detail that it is created paused unless a status is given, and cites the endpoint (POST /v1/ads). It implicitly separates itself from ads_list/ads_update, but never names those siblings explicitly.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no routing to alternatives such as ads_update or adGroups_create. The only implied guidance is that an adGroupId is needed (from schema) and that the tool defaults to a dry run.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known without the description. The description adds nothing beyond the HTTP path — no filter semantics, no result shape, no pagination, no 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?

It is short and front-loaded with no filler, but the brevity comes from omission rather than efficiency. A single sentence that conveys almost no information is not 'concise' in a useful sense.

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

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

For a two-parameter list tool with no output schema and zero schema descriptions, the description should at minimum explain the filters and what is returned. It does neither, leaving the agent to guess at behavior before calling.

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 two parameters (status, adGroupId), so the description carries the full burden of explaining them — yet it says nothing. The enum values in $defs are visible, but how filtering by status or adGroupId behaves (multi-value? defaults? archived included?) is completely 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?

The description names a verb and resource ('List ads') and the underlying endpoint (GET /v1/ads), so the basic operation is identifiable. But it is essentially a restatement of the tool title and gives no distinction from siblings like ads_create, ads_update, or adGroups_list beyond the word 'list'.

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

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

There is no guidance on when to use this tool versus alternatives, no mention of prerequisites, scoping, or pagination expectations. The agent must infer everything from the name and the sibling list.

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

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

The description discloses the most important non-obvious behavior: it is a write that runs as a dry run unless confirm: true is passed, which annotations (readOnlyHint=false, openWorldHint=true) do not convey. It does not disclose whether the update is a partial merge, whether null values clear fields like creativeId/destinationUrl, or whether idempotency is otherwise enforced.

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 tight sentences, with the write/dry-run warning front-loaded where it matters most. The parenthetical field list duplicates the title almost verbatim, which is the only wasted space.

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 nested-body mutation tool with no output schema, the safety model is covered, but the semantics of the nested object are thin: platformNative is unexplained and null-handling on creativeId/destinationUrl is unstated, leaving an agent unsure whether passing null clears or ignores a field.

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 50%; confirm and idempotencyKey are already documented in the schema, and the description's 'set confirm: true' largely repeats that. It names four of the five body fields but omits platformNative entirely, and adds no meaning about nullable fields or merge semantics beyond the schema.

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

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

States a specific verb and resource ('Update an ad') and enumerates the mutable fields (name, status, creative, destination URL), plus the underlying endpoint PATCH /v1/ads/{id}. That is enough to distinguish it from ads_create and ads_list, though the sibling adGroups_update is never acknowledged.

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, no statement about which existing ads are eligible, and no contrast with ads_create or adGroups_update. The only procedural guidance is invocation mechanics (dry run by default), not tool selection.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. Beyond that the description adds only the HTTP path; it says nothing about what an alert represents, whether results are paginated or time-bounded, or how many are typically 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?

The single sentence is front-loaded and free of padding, but its brevity comes from under-specification rather than discipline. There is no wasted wording, yet almost nothing is said.

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, two undocumented parameters, and no description of return shape, the definition leaves an agent guessing about what it will get back and how to filter. The annotations cover safety only, so the description needed to carry more of the load.

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 both parameters, and the description compensates with nothing. In particular it never explains that 'open' is a string enum of "true"/"false" rather than a boolean, nor what clientId scopes the listing to.

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 alerts', plus the underlying endpoint GET /v1/alerts, which confirms it is a read of the alerts collection. The only sibling in the alerts family (alerts_resolve) is clearly a different operation by name, so differentiation is implicit but adequate.

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 alerts_resolve, no mention of defaults, and no indication of what filters are useful in practice. The agent must infer everything from the tool name and the endpoint path.

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 the annotations (readOnlyHint=false, openWorldHint=true), the description discloses the important behavioral trait that nothing is sent unless confirm: true and that no server-side dry run exists, plus that a preview is returned otherwise via the schema. It stops short of describing what resolving changes (status semantics, reversibility) or the effect of the idempotency key.

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 compact sentences with the destructive-gating warning front-loaded right after the operation statement. Nothing is padded, though the 'WRITE:' label style is slightly terse and the endpoint path is somewhat redundant with the tool 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 mutation tool with no output schema, the description covers the safety mechanism and target resource but omits what the resolved state means, whether the action is reversible, and what the preview response contains. Adequate to call safely, but an agent still lacks context on outcomes.

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 67% and both optional parameters (confirm, idempotencyKey) already carry descriptions in the schema. The description reinforces the confirm gating but adds no new syntax, defaults, or constraints beyond what the schema states, so it is roughly baseline.

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

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

States a specific verb and resource ('Resolve an alert') and even names the underlying endpoint (POST /v1/alerts/{id}/resolve), so the agent knows exactly what operation is performed. It does not explicitly differentiate itself from the sibling alerts_list, but the verb makes the distinction obvious.

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 makes clear this is a write that only executes with confirm: true and notes there is no server-side dry run, which is useful execution guidance. However, it gives no guidance on when to resolve versus listing/inspecting alerts (alerts_list), nor any preconditions such as required permissions or valid alert states.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the HTTP endpoint (POST /v1/analytics/breakdown), which is marginal for an agent, and says nothing about how results are grouped, the 500-row limit behavior, currency handling, or whether platforms default to all connected accounts.

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 scope (dimension) and endpoint come first. Its brevity is under-specification rather than verbosity, so it loses a point only because the space saved was not reallocated to useful 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?

For a read-only analytics query with no output schema, the definition is minimally viable: an agent knows roughly what it returns and that a dimension is required. But with a deeply nested body, seven optional fields, and a huge platforms enum all undocumented, an agent cannot call this correctly without reading the schema closely.

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 carries the full burden, yet it only touches the 'dimension' field and omits from/to, limit, clientId, currency, platforms, and byPlatform entirely. The dimension list it does give is incomplete (no 'creative' or 'ad') and uses 'country' where the schema requires 'geo_country', which could actively mislead.

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

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

States a concrete operation (metrics split by a dimension) and enumerates example dimensions, so an agent can tell this is a dimensional breakdown/grouping query. It does not distinguish itself from siblings like analytics_timeseries or analytics_compare, and its dimension list ('country', plus omitted 'creative'/'ad') only loosely matches the enum ('geo_country'), 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 pick this over analytics_timeseries, analytics_compare, analytics_pacing, or analytics_digest, and no mention of prerequisites such as a connected platform or clientId. The reader must infer the use case entirely from the name and the dimension list.

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

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

Annotations already cover the safety profile (readOnlyHint=true) and openness (openWorldHint=true). Beyond that the description adds only the HTTP route, saying nothing about whether comparison requires a lookback window, what comparePrevious changes, or how results are shaped when groupBy=cross_campaign.

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, but it is largely a copy of the title plus an endpoint path, so much of its brevity comes from saying almost nothing. The endpoint reference is the only content not already present in structured fields.

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

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

For a tool whose sole argument is a nested object with nine undocumented properties, no output schema, and a real ambiguity around comparison semantics, one sentence is far from sufficient. An agent cannot determine valid date ranges or the effect of lookbackDays and comparePrevious without guessing.

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 a nine-property nested body, and the description rescues none of it: clientId, currency, firstParty, lookbackDays and comparePrevious get no meaning at all, and from/to date formats and range limits are unstated. The only parameter content is a restatement of the groupBy enum that the schema already enumerates explicitly.

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

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

States a specific verb ("Compare") and resource ("metrics") plus the available grouping axes, which is enough to distinguish this from list-style siblings like analytics_breakdown or analytics_timeseries. It never explicitly differentiates itself from 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 statement of when to choose this over analytics_breakdown, analytics_timeseries, analytics_pacing or analytics_digest, and no prerequisites or exclusions. The only usage signal is the implied "use this when you want comparison", which the agent must infer from the grouping options 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?

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description adds that this is a preview and lists the sections included, but it does not disclose permissions, data freshness, rate limits, or whether alerts and approvals are returned as counts or full records.

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 definition is a single front-loaded sentence with no filler beyond the endpoint reference. It is appropriately brief, though the endpoint suffix may be unnecessary for tool selection.

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

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

The description lists the digest contents but is incomplete for correct invocation because it does not explain date/clientId behavior or output shape. With no output schema and 0% parameter documentation, more detail is needed for an agent to call it 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%, so the description must explain the two parameters. It only hints at clientId via 'per client' and never explains date syntax, defaults, or whether either parameter is optional.

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 definition states a specific resource and scope: a daily digest preview per client, including spend, ROAS, movers, alerts, and pending approvals. This distinguishes it from generic analytics siblings like analytics_breakdown or analytics_timeseries, though it does not use an explicit retrieval verb.

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

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

There is no guidance on when to use this tool versus siblings such as alerts_list, approvals_list, reports_get, or other analytics endpoints. The word 'preview' hints at a preview use case, but the description never states when-not-to-use it or what alternative to choose.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the endpoint, modeling options, and the 14+ day history requirement, but it does not disclose auth or rate limits, how models are selected, or return behavior. Beyond annotations, it adds moderate 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?

A single front-loaded sentence with no filler; method options, duration, minimum history, and endpoint are compactly stated. The endpoint parenthetical is the only arguable redundancy, but it is brief.

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 forecasting tool with a nested request body, no output schema, and zero schema descriptions, the definition is incomplete: it does not explain grouping, date cutoffs, currency, client or campaign scoping, or the response. It covers the high-level operation and a key data precondition but not enough for correct invocation.

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

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

Schema description coverage is 0% for a nested body with fields such as groupBy, asOf, currency, platform, campaignId, and crossCampaignId. The description only hints at horizonDays ('N days') and historyDays ('14+ days' minimum), leaving most parameter meanings and the required groupBy 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?

The description names the specific operation (forecast), the metrics (spend, conversions, value), the horizon (N days), and modeling methods (seasonal naive or Holt). It clearly distinguishes this as the forecasting endpoint, though it does not explicitly contrast it with sibling analytics tools.

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 provides a precondition (needs 14+ days of history), which implies when this tool is valid. However, it gives no explicit guidance on when to use it versus analytics_timeseries, analytics_compare, or other analytics tools, and it does not explain how to choose between seasonal naive and Holt.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. Beyond that, the description only adds the endpoint path and the 5% tolerance default; it says nothing about the response shape, the meaning of the on_track/under/over classification boundaries, or whether 'expected to date' is prorated by day or month. For a metrics tool whose output semantics matter, that 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?

It is a single compact line that front-loads the resource and the output contents. The endpoint path in parentheses is mostly redundant with the tool name, but nothing else 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 nested-body analytics tool with 0% schema coverage, no output schema, and six sibling analytics tools, the description leaves too much unresolved: no scope selection guidance, no parameter meaning, and no sense of the returned pacing figures. It is readable but not sufficient for confident invocation.

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

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

Schema description coverage is 0% and the body object nests seven undocumented properties (asOf, clientId, currency, platform, tolerance, campaignId, crossCampaignId). The description only explains the tolerance default of 5%, leaving asOf date semantics, currency format expectations, and whether campaignId and crossCampaignId are mutually exclusive entirely unaddressed.

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

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

The description names a specific analytics resource and enumerates what the response covers: spend vs expected to date, projected end, and on_track/under/over status. That is more specific than a bare resource name and distinguishes it from analytics_forecast and analytics_breakdown. It does not explicitly say how it differs from those siblings, keeping it at 4 rather than 5.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the sibling tools (analytics_forecast, analytics_breakdown, analytics_timeseries, analytics_digest) that an agent could pick instead. The only usage-like hint is the '(5% default)' tolerance note, which describes a parameter rather than when to select this tool.

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 usefully reinforces the annotations by declaring the tool 'advisory' and 'never writes', which resolves the confusion of a POST endpoint that is actually read-only. Beyond that it says nothing about what the response contains, how the marginal-ROAS equalization is constrained, or what the minFactor/maxFactor bounds do to results.

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 key qualifier ('advisory', 'same total') up front and the endpoint appended as reference. Dense with jargon like 'marginal ROAS' but nothing is wasted or redundant.

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

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

For a tool whose only input is a large nested object with zero documented fields and no output schema, a one-line description is far from sufficient to invoke it correctly. An agent cannot determine valid date ranges, budget units, or the meaning of the factor bounds from the provided text.

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% on a deeply nested body with from/to dates, clientId, platform, campaignId, crossCampaignId, currency, min/maxFactor and a totalDailyBudget micros object. The description supplies no parameter meaning whatsoever, leaving an agent to guess date semantics, currency format, and budget units.

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 resource and operation: advisory budget reallocation that equalizes marginal ROAS while holding total spend constant. That is distinguishable from the other analytics_* siblings (breakdown, pacing, forecast, synergy, saturation), 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?

There is no guidance on when to choose this over analytics_forecast or analytics_saturation, no stated prerequisites (e.g., that it needs a date range and a total budget), and no note on whether the caller should follow up by actually applying changes elsewhere.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds only the HTTP path (POST /v1/analytics/saturation) and a hint at returned fields; it does not say whether the fit requires a minimum data volume, how confidence is derived, whether results are cached, or what happens for sparse campaigns. Marginal added context beyond structured data.

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

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

It is one short, front-loaded sentence with no filler, which is good, but the brevity comes at the cost of under-specification rather than efficiency. Nothing extraneous, yet nothing that earns additional credit.

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, an eight-field nested body at 0% description coverage, and no sibling differentiation, the definition is too thin for an agent to call this correctly. Key facts an agent needs (valid date conventions, whether groupBy must match the provided platform/campaignId, expected response shape) are all absent.

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

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

Schema description coverage is 0% and the single body parameter is a nested object with eight undocumented fields (from/to, groupBy, clientId, currency, platform, campaignId, crossCampaignId). The description only implies the groupBy choice via 'per platform or campaign' and says nothing about the date range semantics, currency handling, or how platform/campaignId/crossCampaignId 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?

The description names the analytical artifact (a diminishing-returns fit with marginal ROAS and a confidence flag) and the grouping dimension (platform or campaign), which is more specific than a bare label. However it is essentially the title plus an endpoint path, with no verb describing the operation and no differentiation from sibling analytics tools such as analytics_forecast, analytics_pacing, or analytics_reallocation that an agent could use to pick the right 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?

There is no when-to-use guidance: nothing states which questions this fit answers that analytics_forecast or analytics_reallocation do not, nor any prerequisite (date range bounds, client context, minimum spend). Usage can only be inferred from the phrase 'diminishing-returns fit', which leaves the agent guessing among many sibling analytics endpoints.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. Beyond that the description only adds the '(not causal)' caveat about how to read the lagged correlation, and says nothing about the POST body requirement, computation cost, or the lag/platform caps that shape results.

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 a single short fragment with no wasted words, but the space saved is space that should have been used; the only structural element is the trailing endpoint path, which is metadata rather than guidance.

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?

This is a complex analytics endpoint with a ten-property nested request body, no output schema, and no annotation-level detail about returns. The description does not explain required date range semantics, defaults for maxLag/maxPlatforms, or what the response contains, leaving the agent unable to call it correctly from the definition alone.

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 top-level parameter is a nested body with ten undocumented properties (maxLag, lookbackDays, maxPlatforms, currency, platform, campaignId, crossCampaignId, clientId). The description supplies no meaning for any of them; only faint topical hints ('lagged' -> maxLag, 'platform overlap' -> maxPlatforms) exist, which is far short of compensating for the coverage 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?

The description names the analytics concepts the endpoint produces (blended MER, platform overlap, assists, lagged spend correlation) which does differentiate it from siblings like analytics_breakdown or analytics_pacing. However it is a bare noun phrase copied from the title with no verb and no statement of what the tool actually returns or computes, so the agent must infer the operation.

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 exclusions, and no reference to the many adjacent analytics siblings (analytics_compare, analytics_timeseries, analytics_saturation, analytics_reallocation). The parenthetical '(not causal)' hints at interpretation limits but says nothing about when this tool should be selected over alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful facts not in the annotations: daily granularity, that values are expressed in the reporting currency, and the underlying POST endpoint. It says nothing about how missing data days, currency conversion, or entity defaults are handled.

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

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

A single front-loaded sentence with zero redundancy and no filler. It is efficient, though the brevity comes at the cost of omitted parameter guidance rather than being a model of tight prose.

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

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

A read-only analytics query with a seven-field nested body, no output schema and no parameter documentation leaves the agent guessing about defaults, row shape and optional filters. For this complexity the description should say at minimum what entityIds omission means and what a response row looks 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 description coverage is 0% and the body nests seven properties, yet the description only gestures at date range and currency. It adds no meaning for entityType (campaign/ad_group/ad), entityIds, firstParty or lookbackDays, including what happens when entityIds is omitted, which is the most consequential ambiguity here.

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

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

The description names a specific resource (daily metrics for entities), a scope (over a date range) and a unit (reporting currency), plus the REST endpoint. That is enough for an agent to know what the tool returns, but it never distinguishes it from siblings such as analytics_breakdown, analytics_compare or analytics_pacing, which all operate on the same entity/metric space.

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 guidance and no mention of the near-identical analytics_* siblings. An agent has to infer from the name alone whether this or analytics_breakdown is the right call.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the mutation profile is known. The description usefully adds that the operation has no server-side dry run and is gated on confirm, but the schema's confirm field already says it returns a preview, and it never clarifies what "session only" means, whether the key secret is returned once, or that minted credentials persist until apiKeys_revoke.

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 with the action and endpoint front-loaded and zero filler. The telegraphic style ("WRITE: not executed unless confirm: true") is terse but still parses cleanly.

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 credential-minting mutation with a nested body, no output schema, and only sparse annotations, an agent still lacks critical context: what the returned key material looks like, whether it is shown once, and what "session only" constrains. Adequate as a pointer but not complete for correct, safe invocation.

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

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

Schema description coverage is 67%, so the schema carries most of the load for confirm and idempotencyKey. The description adds no meaning about the nested body fields (scopes, clientId, expiresAt, guardrailIds) or least-privilege scope selection, which would be the highest-value thing a minting tool could explain.

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 ("Mint an API key") plus the concrete endpoint POST /v1/api-keys, which distinguishes it from the read/revoke siblings apiKeys_list and apiKeys_revoke. It does not name those siblings explicitly, so differentiation is inferable rather than stated.

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

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

The confirm:true requirement and the note that nothing executes without it give usable invocation guidance. However, there is no explicit when-to-use versus alternatives (e.g., how this differs from appCredentials_set or tracking_createIngestKey for other credential types), and no prerequisites such as required scopes to mint a key.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that secrets are not returned — but says nothing about pagination, ordering, or what metadata each key carries.

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

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

A single short sentence, front-loaded with the action and resource. The '(no secrets)' and endpoint parenthetical are compact, though the endpoint adds little for an agent that already has the tool 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 annotations covering safety, the description is close to sufficient, but with no output schema it does not say what fields a listed key exposes (id, name, created date, last used). That gap is minor but real.

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 parenthetical endpoint reference is harmless but adds no 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 and resource ('List API keys') and adds a scope qualifier ('no secrets') that tells the agent the response is redacted. It is clearly distinct from the sibling apiKeys_create and apiKeys_revoke, though the phrasing largely restates the title.

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, no prerequisites, and no named alternative. The agent must infer that this is the read-only counterpart to apiKeys_create/apiKeys_revoke from the name alone.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the safety profile is partly covered, but the description adds genuinely new information: nothing is sent without confirm: true, there is no server-side dry run, and a request preview is returned otherwise. What it omits is the effect of revoking (immediate invalidation of the key, irreversibility).

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, front-loaded with the action and the write gate, with zero filler. The 'WRITE:' marker makes the mutation status scannable at a glance.

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 destructive, idempotent-keyed mutation with no output schema, the description covers the confirmation flow but leaves out consequences (does the key stop working immediately, is revocation permanent, can it be undone by creating a new key) and doesn't mention that idempotencyKey is auto-generated. Minimum viable rather than 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 67% and the schema itself already documents confirm and idempotencyKey in detail, so the description's mention of the confirm gate largely restates structured data. The bare `id` parameter gets no explanation in either place, and at 3 params the 3 baseline is appropriate.

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

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

The description gives a specific verb+resource ('Revoke an API key') and even the underlying endpoint (DELETE /v1/api-keys/{id}), so the agent knows exactly what is being affected. It doesn't explicitly contrast with siblings like apiKeys_list or apiKeys_create, but the verb 'revoke' is unambiguous enough to separate it.

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 explains the execution mechanics (must pass confirm: true) but gives no guidance on when to revoke versus other options, no prerequisites such as required scopes or ownership, and no warning about verifying the key id first. Usage is implied by the tool name 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the underlying endpoint (GET /v1/app-credentials) and, more usefully, indicates the response shape is platform entries with their field names and accepted fields. It says nothing about whether only configured platforms or all supported platforms are returned, nor about auth/workspace scoping.

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 compact sentence with the endpoint in parentheses — no padding or repetition. It loses a point only because the sentence is noun-phrase shaped rather than leading with an action, which makes the purpose slower to parse.

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

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

A no-param, no-output-schema read is a simple tool, and the description does sketch what comes back. However, for a 'list what's stored' tool the critical question — configured-only vs. all available platforms, and the shape of each entry — is left ambiguous, which is where an agent would most likely misread 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, so there is nothing for the description to disambiguate; the baseline for a 0-param tool applies. The parenthetical endpoint reference is a harmless extra detail.

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

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

The title/description conveys the resource (BYO app credentials) and what is returned (stored platforms plus field names and accepted fields), but it omits an explicit verb — an agent has to infer 'list' from the tool name suffix. It is distinguishable from appCredentials_set/remove by the 'stored' framing, but that differentiation is implicit rather than stated.

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

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

There is no when-to-use guidance and no mention of the obvious alternatives, appCredentials_set (to configure a platform) and appCredentials_remove (to delete one). An agent reading only the description gets no cue about which of these three to pick.

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 destructiveHint=true and idempotentHint=true, but the description adds genuinely new behavior: nothing is sent without confirm:true, and crucially there is no server-side dry run, so the preview is the only safety net. The 204 also tells the agent to expect an empty body. It stops short of describing auth/scope requirements or what happens if the credential does not exist.

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 compact, front-loaded sentences with zero filler; the destructive gating is stated up front. The only waste is the redundant "(204)" repeated from the title and again as the response code context.

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

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

For a three-parameter destructive call with no output schema, the definition covers the safety gate well. What is missing is the platform selector's meaning and any failure-mode behavior for a credential that does not exist, which matters because there is no server-side dry run to catch mistakes.

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 67%, so confirm and idempotencyKey are already documented in the schema, and the description's note about confirm largely restates that. The required platform parameter, backed by a very large enum with no description, gets no semantic explanation in the description — nothing about which credential is targeted or what happens if the platform has no stored credential.

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

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

The description states a specific verb and resource ("Remove a workspace app credential") and pins down the exact endpoint (DELETE /v1/app-credentials/{platform}) plus the expected 204 response. It is clearly distinguishable in intent from appCredentials_list and appCredentials_set, though it never names those siblings explicitly.

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

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

Usage context is only implied by the verb and HTTP method; there is no explicit statement of when to use this versus appCredentials_set (e.g. whether set overwrites or this is the only way to revoke). The confirm:true requirement is the one concrete operative instruction.

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 meaningful context beyond annotations: values are write-only, the effect is "session only", and there is explicitly no server-side dry run, so the confirm path returns a preview rather than a real validation. Annotations already declare the write and idempotent profile, and the description stays consistent with them; it stops short of stating what happens to pre-existing credential fields on overwrite or what permissions are required.

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 tightly packed sentences: purpose and endpoint first, then the write-gating constraint. Nothing is redundant and the most safety-critical fact (confirm required) is front-loaded in the second sentence.

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

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

For a credential-writing tool with a free-form nested body object, no output schema, and 25% of parameters undocumented, the description omits the things an agent most needs: which body keys are required per platform, whether a set replaces or merges existing values, and what "session only" implies for persistence.

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 75% and the schema already explains confirm, idempotencyKey and the write-only body, so the description largely restates structured content. It adds no meaning about which body field names the platform expects or how the platform enum value maps to the stored credential.

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

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

Specific verb+resource: "Set a workspace app credential for a platform", reinforced by the concrete endpoint PUT /v1/app-credentials/{platform}. It is clearly distinguishable from appCredentials_list and appCredentials_remove by verb alone, though it never names 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?

The only usage condition given is the mechanical gate: "not executed unless confirm: true". There is no guidance on when to prefer this over connections_createWithCredentials or connections_create, which also appear to store credentials, so the agent must infer the boundary.

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 only give readOnlyHint=false and openWorldHint=true, so the description earns credit for clarifying the write semantics: nothing executes without confirm: true and there is no server-side dry run, i.e. confirm:false only returns a client-side preview. It still omits the outcome of consuming (is the link single-use, does it irreversibly record a decision, what permissions/expiry apply).

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 tightly packed sentences with the endpoint and the write gate front-loaded; nothing is redundant. The brevity is close to under-specification, but every sentence 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?

For a no-output-schema mutation tool this is the minimum viable: it discloses the write gate and idempotency, but leaves the token's provenance, the resulting state change, and one-time-use behavior unexplained. An agent could call it safely but not predict its effect.

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?

With 67% schema coverage, confirm and idempotencyKey are already documented in the schema, and the description largely restates the confirm behavior rather than adding new meaning. The token parameter is completely undetailed in both places — no explanation of where the token comes from or its lifetime.

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?

It names a verb ('Consume') and resource ('the link') plus the underlying endpoint, but 'consume' does not tell an agent what the operation actually does — approve, reject, or execute a pre-configured decision — and no decision field exists in the schema, so the effect stays opaque. It also fails to distinguish itself from the nearby approvalLinks_preview / approvalLinks_slackInteraction 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?

The confirm:true gate implicitly signals this is the real-execution counterpart to the preview flow, but the description never says when to call it versus approvalLinks_preview or the approvals_approve/approvals_reject siblings. 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond restating 'GET' — it does not say whether the token is public/unauthenticated, whether the response is raw HTML meant for rendering, or whether access can fail on expired links.

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 one short, front-loaded line with no filler, but the brevity stems from under-specification rather than discipline; the path fragment is the only substantive content.

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 (one path parameter, no output schema) and the annotations cover read-only semantics, yet the description still leaves the agent without the token's origin or the fact that the return value is a renderable HTML document rather than JSON.

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 required parameter. The only hint is the '{token}' placeholder in the path, which implies it is the approval-link token, but there is no explanation of where that token comes from or what makes it valid.

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 verb ('Preview') and, via the HTTP route GET /v1/approval-links/{token}, identifies the resource as an approval link. However, it is essentially the title restated plus a path, and it does not distinguish this tool from siblings such as approvalLinks_decide, publicReports_html, or invites_preview.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no named alternative. An agent cannot tell from this text when to call preview versus approvalLinks_decide or approvalLinks_slackInteraction.

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 only declare readOnlyHint=false and openWorldHint=true. The description adds real behavioral context beyond that: this is a write that is not executed without confirm:true, and there is no server-side dry run, so the confirm gate is the only preview mechanism.

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 short and front-loads the operation and write-gating rule. The raw endpoint path is somewhat redundant with the name/title but does help locate the underlying API route.

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 mutation tool with openWorldHint and no output schema, the description covers the critical safety behavior (confirm gate, no dry run) but leaves out what the callback does with the incoming interaction and what the preview response contains. It is adequate to call safely, not 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 50%: confirm and idempotencyKey are documented in the schema, and the description usefully reinforces confirm's execute-vs-preview semantics. But workspaceId and channelId have no meaning or format explained in either place, so the description only partially compensates for the coverage 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?

The description names the resource (Slack interactivity callback at the /v1/integrations/slack/{workspaceId}/{channelId}/interactions endpoint) and flags it as a WRITE, but the verb 'callback' does not say what the tool actually does with an interaction payload. It also gives no differentiation from nearby approvalLinks siblings such as approvalLinks_decide or approvalLinks_preview.

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 a concrete precondition ('not executed unless confirm: true'), which implies how to invoke it safely, and the schema clarifies a preview is returned without confirm. However, there is no guidance on when to use this tool versus approvalLinks_decide/preview or crosspost_resolve, so routing is left to inference.

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

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

Annotations only say readOnlyHint=false and openWorldHint=true, so the description earns credit for disclosing that this is a WRITE that is not executed unless confirm: true and that there is no server-side dry run. It still omits what the approval actually does downstream and whether it is reversible, keeping it below 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 compact sentences with the mutation warning front-loaded, and no filler. The repeated parenthetical from the title is slightly redundant but not costly.

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 write tool with no output schema, it covers the critical safety mechanic (confirm gate, no dry run) but says nothing about required permissions, what the returned preview contains, or side effects of approving. Adequate minimum, with clear gaps.

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 67%, with the undocumented parameter being id; the description fills exactly that gap by defining id as the action id. The confirm explanation largely restates the schema text, but the id clarification plus the execution gate adds real meaning beyond the structured fields.

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 plus the underlying endpoint (POST /v1/approvals/{id}/approve), and clarifies that the id is an action id rather than an approval id. It does not explicitly distinguish itself from siblings like approvals_reject or approvalLinks_decide, 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 statement of when to approve versus reject, or when to use approvalLinks_decide instead. The only conditional guidance is the confirm flag, which is about execution mechanics, not tool selection.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the write nature is known. The description adds genuinely useful context beyond that — the confirm gate and the fact that there is no server-side dry run — but says nothing about whether comments are editable or deletable, who may post them, or what state changes.

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 compact clauses, front-loaded with purpose and immediately followed by the one behavioral constraint that matters. 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 simple write tool with a nested body and no output schema, the definition covers the execution gate but leaves the payload semantics (what 'id' identifies, body formatting/limits beyond the schema's maxLength) and the returned preview unexplained. Adequate but with visible gaps.

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 50%: confirm and idempotencyKey are already documented in the schema, and the description's confirm note merely restates that. The undocumented 'id' and nested 'body' parameters get no added meaning from the description, though the endpoint path weakly implies id is the approval request 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?

The description states a specific verb and resource ('Comment on an action') and even pins the endpoint POST /v1/approvals/{id}/comments, which cleanly separates it from approvals_listComments, approvals_approve and approvals_reject. It stops short of naming those siblings explicitly, which keeps 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?

It gives one concrete precondition — the write is not executed unless confirm: true — which is real usage guidance. But there is no guidance on when to comment versus approve/reject, no statement that the action must be pending, and no permission prerequisites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds only the raw endpoint path, disclosing nothing about pagination, ordering, result volume, or whether results are scoped to the current workspace — behavior an agent would need for a cross-account listing.

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 that front-loads the resource and the default behavior, with no filler. The parenthetical HTTP path is arguably waste for an agent caller, but it costs little.

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 read tool with no output schema, the definition is minimally viable. It still leaves open return shape, pagination, and whether the list is workspace-scoped, which matter given openWorldHint=true.

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 carry the burden. It does add one genuinely useful fact absent from the schema — that omitting status yields pending — but it explains nothing about the approved/rejected/expired values or any filtering interactions.

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

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

States a clear verb and resource ('List approvals') and adds the useful qualifier that listing defaults to pending status. It does not distinguish itself from siblings such as approvals_listComments or approvalLinks_decide, but the operation itself 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 'default: pending' note implies the primary use case (reviewing the pending approval queue) and that passing a status widens the query, but there is no explicit when-to-use versus when-to-use-a-sibling guidance or any statement of scope.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description contributes nothing further: no pagination or ordering behavior, no indication of what a comment record contains, and no note on whether comments are public or scoped to approvers.

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 clauses with zero filler and the resource and endpoint front-loaded. It is efficient, though it leans heavily on the URL path as its information carrier instead of stating the scope in prose.

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 read-only list tool with annotations covering the safety profile, the definition is minimally sufficient to invoke correctly. With no output schema, however, the description should at least hint at the returned shape and whether results are paginated, and it does not.

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 carries the burden for the single 'id' parameter, and it partially does so by revealing through the URL path that id is an approval ID rather than a workspace or comment ID. However, it gives no format or example value for that 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?

The description pairs a specific verb ('List') with a specific resource ('comments') and, via the embedded endpoint path GET /v1/approvals/{id}/comments, makes clear the comments are scoped to one approval. That implicitly separates it from the sibling approvals_comment (which writes a comment), though the description never names 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 guidance on when to call this versus alternatives such as approvals_list or approvals_comment, and no stated preconditions (e.g., that the approval must be visible to the caller). The embedded endpoint path is the only hint about context.

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

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

Annotations only say readOnlyHint=false and openWorldHint=true; the description adds genuinely useful behavior the annotations cannot convey — that nothing is sent unless confirm: true and that there is no server-side dry run, so the preview is the only safety net. It stops short of stating whether a rejection is reversible or who gets notified.

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 compact clauses, front-loaded with the verb and the critical security constraint. The telegraphic "WRITE:" prefix and repeated endpoint syntax are slightly cryptic but cost almost nothing in length.

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

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

For an irreversible mutation with no output schema and no destructive hint, the description covers the execution gate but omits consequences (irreversibility, notifications, effect on the approval workflow) and leaves body.reason unexplained. An agent could invoke it correctly, but not predict what happens after.

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?

With 50% schema coverage, the description contributes meaning for two parameters: it clarifies that id is an action id (not an approval id) and explains the confirm gate. It says nothing about the nested body.reason field or idempotencyKey, leaving half the surface documented only by 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?

"Reject" supplies a verb and the endpoint path plus a parenthetical that the id is an "action id", so the agent knows this targets an approval action. However, it never states that it rejects a pending approval request, nor what rejecting entails, so the purpose is only inferable from the tool name and the sibling set.

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 choose this over approvals_approve or approvalLinks_decide, and no statement of preconditions (e.g., must the approval be pending, must the caller be a designated approver). The only conditional mentioned is the confirm gate, which is an execution safeguard rather than a use-case 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?

The annotations already flag destructiveHint=true and idempotentHint=true, but the description adds genuinely new behavior: nothing executes without confirm: true and there is no server-side dry run, so the confirm flag is a real enforcement gate rather than an optional nicety. It does not say what happens to pending approvals already routed to a removed approver, which keeps it below 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 short sentences with zero filler: the operation and endpoint come first, followed immediately by the write-safety constraint. Nothing is repeated from the schema beyond what adds meaning.

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 destructive single-parameter delete with no output schema and rich annotations, the definition covers what the agent most needs: the gate flag and the absence of a server-side dry run. It could still state irreversibility and the effect on in-flight approvals, which is the main remaining gap.

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

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

Schema description coverage is 67%, with confirm and idempotencyKey already documented in the schema; the description reinforces confirm as an execution gate ('not executed unless confirm: true'). The required id parameter carries no description in either place, so the semantics of what identifier is expected (approver id vs. user id) remains ambiguous.

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

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

The description states a specific verb and resource ('Remove an approver') and pins it to an endpoint (DELETE /v1/approvers/{id}), so the agent can distinguish it from approvers_list and approvers_registerSelf. It stops short of explicitly naming those siblings, so it is clear but not fully differentiated.

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

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

Usage is implied by 'Remove an approver' and the confirm gate tells the agent how to actually execute, but there is no explicit when-to-use versus alternatives guidance, no mention of prerequisites (permissions, whether the approver must be inactive), and no warning about irreversibility.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the underlying HTTP endpoint, which conveys nothing beyond that — no indication of result ordering, scope (workspace-wide vs. per-link), or pagination behavior for a list endpoint.

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 verb and resource stated first, and no filler. The parenthetical endpoint is arguably redundant but costs little.

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-only list with no output schema, the description is minimally adequate but thin: an agent cannot tell what an 'approver' record contains or whether the list is scoped to one link or the whole workspace. Adding one clause on scope 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 there is nothing for the description to disambiguate; baseline is 4. No misleading parameter guidance is present.

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

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

States a specific verb ('List') and resource ('approval-by-link approvers'), which distinguishes it from approvals_list and approvers_registerSelf/approvers_delete. It does not explicitly name those siblings or explain the boundary, but the scope wording is specific enough to route an agent.

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 approvals_list, approvers_registerSelf, or approvers_delete. The description gives no preconditions, no exclusions, and no alternative routing, leaving usage 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?

Annotations only give readOnlyHint=false and openWorldHint=true; the description adds genuinely new behavior: nothing is sent unless confirm:true, and there is no server-side dry run, so the preview is the only safety net. It stops short of describing what registration does to existing approver state or any permission requirements.

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

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

Two short sentences, front-loaded with the action and endpoint, then the write-gate caveat. Nothing redundant and the most decision-relevant fact (confirm required) is stated up front.

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 single-endpoint mutation with no output schema, the definition covers the action, the endpoint, and the confirm/preview contract, which is what an agent needs to invoke it safely. Minor gaps remain around auth/permission requirements and the meaning of the slackUserId body field.

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 67% and confirm/idempotencyKey are already documented in the schema, so the description adds little. The nested body.slackUserId is only constrained by a regex pattern and the description never explains whose Slack ID it should be or what happens when omitted.

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 ('Register yourself as approver') and pins the exact endpoint (POST /v1/approvers/me). This clearly separates it from the sibling read/delete operations approvers_list and approvers_delete.

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 by the 'register yourself' phrasing; there is no explicit statement of when an agent should call this versus approvers_list or an invite flow, nor any prerequisite (auth/role/workspace) guidance. The confirm gating is explained, but that is execution mechanics rather than when-to-use guidance.

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

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

Annotations only state readOnlyHint=false and openWorldHint=true; the description adds real behavioral context by flagging that nothing is executed without confirm: true and that there is no server-side dry run, so the preview is client-side only. It stops short of saying what happens on partial failures or whether duplicates are merged.

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 with the operation stated first and the write gate second, so the critical safety fact is easy to spot. The stacked parentheticals (title repeated, then endpoint, then WRITE warning) make it slightly denser than necessary.

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 write tool with a nested body, no output schema, and a 4-parameter surface, the description covers the safety model but leaves the operational picture thin: no row format, no batching limit, no idempotency behavior, and no description of what the preview response 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?

With schema description coverage at 50%, confirm and idempotencyKey are already documented in the schema, so the description only reinforces the confirm gate. It adds nothing about the 'id' parameter being the audience/list identifier, the per-row email/phone shape, defaultCountryCode, or the maxItems constraint on rows.

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 ('Add contacts to a customer list') plus the underlying endpoint POST /v1/audiences/{id}/members. It is clearly distinguishable from audiences_removeMembers and audiences_sync by the 'add' verb, though it never names those siblings explicitly.

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

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

The consent requirement and the confirm: true gate imply when the tool is usable and what must be done before calling, which is useful guidance. However, there is no explicit statement of when to prefer this over siblings (e.g., sync vs addMembers), no prerequisites about the list existing, and no mention of the 50,000-row batch ceiling.

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 only declare readOnlyHint=false and openWorldHint=true; the description adds the meaningful facts that the call is gated behind confirm: true and that omitting it returns a request preview rather than executing. It does not cover failure behavior on consent rejection or the 201 response semantics, but it substantially exceeds the annotation 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 short sentences with the resource and endpoint front-loaded and the write-gate warning immediately after. The parenthetical '201' and repeated title phrasing are slightly redundant but cost little.

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 write tool with a nested object payload and no output schema, the definition covers the safety gate well but leaves the body shape — row limits, email/phone requirements, consent basis — entirely to the schema. An agent knows how to execute safely but not what a valid payload looks like beyond required fields.

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 67%, with confirm and idempotencyKey already documented in the schema; the description reinforces confirm's gating role. The nested body fields (rows, consent.basis, clientId, defaultCountryCode) get no added meaning beyond 'contacts with confirmed consent', leaving the largest part of the payload 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?

The description states a specific verb and resource — creating a customer-list audience from contacts with confirmed consent — and pins it to POST /v1/audiences. The phrase 'customer-list audience' implicitly separates it from audiences_createLookalike and audiences_addMembers, 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?

It gives a strong execution precondition: nothing is sent unless confirm: true, and there is no server-side dry run. However, it never says when to choose this over audiences_addMembers (adding to an existing list) or audiences_createLookalike, so the routing decision 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?

Annotations only say readOnlyHint=false and openWorldHint=true; the description adds genuinely new context by flagging the tool as a WRITE, stating that nothing is sent unless confirm: true, and noting there is no server-side dry run. What is still missing is the blast radius (new audience created on the ad account) and any rate-limit or async-processing behavior.

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

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

Two compact sentences with the write-safety caveat front-loaded into the second sentence; nothing is padded. It does largely restate the title verbatim, which costs a little value but no clarity.

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 creation tool with a nested required body of five undocumented fields and no output schema, the description leaves a lot unstated — what the returned preview looks like, what constraints apply to ratio, and how idempotency behaves on retry. The write-gating note is helpful, but the parameter surface remains opaque.

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 67% but only for the top-level confirm and idempotencyKey, both of which already have schema descriptions. The nested body's five required fields (name, adAccountId, sourceAudienceId, countries, ratio) carry no descriptions in either the schema or the description, and the description never explains the ratio range, country-code format, or what sourceAudienceId must reference.

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

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

The description gives a specific verb, resource, and scope ("Create a lookalike of a synced customer list on an ad account") plus the HTTP endpoint, which clearly separates it from audiences_createList or audiences_addMembers. It stops short of explicitly naming a sibling, but the distinctive "lookalike" resource makes the intent 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 confirm: true requirement makes the invocation contract concrete, but there is no guidance on when to choose this over audiences_createList or when a source audience must first be synced. Prerequisites (source audience existence/sync state) and exclusions are left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the '(GET /v1/audiences/{id})' suffix only reinforces that read-only nature. The description adds no context beyond annotations: it doesn't say what 'links' contains, what happens on a missing audience, or whether related expansions are 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?

A single front-loaded sentence with the verb and resource first and the endpoint appended. Nothing is wasted, though the raw endpoint reference is of limited value to an agent that cannot call HTTP directly.

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 read tool with no output schema, the definition is nearly sufficient: it names the record fetched and its links, and annotations cover the safety profile. What's missing is any description of the returned audience/links shape, which matters somewhat since no output schema exists.

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

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

Schema coverage is 0% for the single required 'id' parameter, so the description must compensate. The path template '{id}' does establish that the parameter is an audience identifier, but it gives no format, source, or example beyond that minimal hint.

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 ('Get one audience') and scopes it to a single record, which implicitly distinguishes it from audiences_list. The added 'with its links' signals extra payload, though what 'links' means is never explained.

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: fetch a single audience by id. It never names audiences_list as the alternative for browsing, nor says when a detail fetch is preferable to list, and gives no preconditions such as requiring a known id.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds a genuine data-scope guarantee (member data is never included) and the underlying endpoint path, but says nothing about pagination, result caps, or ordering for a list operation across an open-world system.

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 compact sentence with the scope statement front-loaded and no filler. The nested parentheses around the exclusion and the endpoint path make it slightly harder to parse than necessary.

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

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

For a simple read-only list tool with annotations and no output schema, the description covers identity and scope but leaves the only parameter and all return-shape expectations (fields per audience, pagination) unexplained. Adequate, not 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 description never mentions the single parameter clientId, so its meaning (client/workspace scoping, whether omission means "all clients") is undocumented everywhere. This is the clearest gap in the definition.

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 verb and resource ("List audiences") and states the payload scope ("with their ad-account links"), plus an explicit exclusion ("never member data") that separates it from audiences_addMembers/removeMembers/get without reading their schemas. It stops short of naming those siblings, so it is not 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?

The exclusion "never member data" implies that member-level data lives behind a different tool, but the description never names the alternative or states a positive when-to-use condition. Usage is inferable from the verb rather than spelled out.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false. The description adds genuinely new behavior: the two-phase preview/execute model and the absence of a server-side dry run, which materially changes how an agent must call it. It stops short of saying what is destroyed alongside the audience (members, campaign references).

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 action and endpoint, then the safety constraint. Minor waste in repeating the title verbatim ("Delete an audience (204)") and in the doubled parentheses, but no sentence is superfluous.

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 three-parameter destructive delete with no output schema, the definition covers the endpoint, the required confirm flag, the preview fallback and the 204 result. Only the blast radius of the deletion is unstated, which is a modest gap rather than a blocking one.

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

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

Schema coverage is 67% and both confirm and idempotencyKey are documented in the schema, so the schema carries most of the weight. The description restates the confirm contract but adds nothing about the id parameter or when to supply an idempotencyKey. Baseline 3 for a largely self-documenting schema.

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

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

States a specific verb and resource ("Delete an audience") plus the underlying HTTP endpoint (DELETE /v1/audiences/{id}) and success status (204). That is enough to distinguish it from nearby siblings such as audiences_removeMembers or audiences_list without opening a schema.

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

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

Explicitly explains the execution gate: nothing is executed unless confirm: true, and there is no server-side dry run, so the only preview path is the client-side one. It does not spell out when to prefer this over e.g. trimming members, but for a destructive delete the invocation condition is the useful guidance and it is present.

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 the readOnlyHint=false/openWorldHint=true annotations, it discloses that nothing is sent unless confirm is true, that there is no server-side dry run, and that the removal is staged locally then pushed via sync mode replace. That is genuinely useful mutation context; it stops short of saying what happens to non-matching rows or whether removals are 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?

Two compact sentences with the action first and the write-gate second; no filler. The inline raw endpoint path is slightly noisy but earns some place as a routing cue.

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 nested-body write tool with no output schema and only 50% parameter coverage, it adequately covers the safety/dry-run story but omits matching semantics, partial-match behavior, and the shape of the returned preview. Enough to call it, not enough to predict the outcome.

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?

With 50% schema coverage, the description only reinforces the confirm flag and 'matching contacts', which loosely implies rows match by email/phone. It adds nothing about defaultCountryCode, idempotencyKey, the 50,000-row cap, or matching semantics for rows, leaving half the parameters to the schema alone.

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 ('Remove matching contacts locally') plus the endpoint, and the phrase 'push with sync mode replace' distinguishes the local removal from the server-side push behavior. It does not name a specific sibling (audiences_addMembers, audiences_remove, audiences_sync) for contrast, 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?

The confirm: true gate implies when the call actually executes, and 'push with sync mode replace' hints at a relationship with sync, but no alternative tool is named and no explicit when-not-to-use condition is given. Usage must largely be inferred by comparing with audiences_addMembers/audiences_sync.

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 readOnlyHint=false and openWorldHint=true, the description adds genuinely useful behavior: this is a WRITE, it will not execute unless confirm is true, and there is no server-side dry run, so confirming is the only safeguard. It stops short of saying what replace mode does to existing audience membership, which is the most consequential unknown for a write.

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 action, ending with the safety warning. Slightly awkward API-style dotted naming ('audience.create') forces the reader to translate to tool names, but otherwise there is no wasted wording.

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 four-parameter mutation with a nested body, openWorldHint, and no output schema, the description covers the lifecycle and the confirm gate but leaves the mode semantics and the consequence of a replace sync unexplained. An agent can call it, but could plausibly wipe membership by choosing replace without any warning here.

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

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

Coverage is 50%: confirm and idempotencyKey are documented in the schema, and the description partially compensates by revealing via the POST path that 'id' is the audience list id and by framing 'body' as targeting an ad account. However, the add-vs-replace 'mode' enum — the single most important semantic choice for a sync — is explained nowhere.

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 concrete verb and resource ('Push the list to an ad account') and distinguishes the sync step from the initial create step in the audience lifecycle. It does not name the actual sibling tools (audiences_createList, audiences_createLookalike), so an agent must infer the mapping from 'audience.create'/'audience.sync' to the hyphen-free tool names.

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 supplies clear routing context: use create the first time, use sync on subsequent pushes. It also states the hard precondition that nothing is sent without confirm: true. It lacks explicit exclusions (e.g., when to use audiences_remove or audiences_addMembers instead) and never names the sibling tools directly.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds nothing beyond that — no indication of default limit, ordering, retention window, or pagination behavior for a log-listing endpoint.

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 a single short sentence with no padding, but the brevity comes from omission rather than discipline; there is no front-loaded statement of what the tool returns or how to narrow results.

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 four-parameter filtered log query with no output schema and no field documentation anywhere, the description leaves the agent unable to construct a meaningful call beyond a bare request.

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 four parameters (limit, actionId, entityId, entityType), and the description compensates for none of it — not even what entityType values are accepted or what limit defaults to.

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?

"Audit log entries (GET /v1/audit)" restates the tool title and name with no verb, no scope, and no statement of what an audit entry contains. The parenthetical endpoint adds nothing an agent can use to distinguish it from sibling security/members_audit tools.

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 when-to-use guidance at all, and no mention of alternatives such as members_audit or security_verifyAudit, which an agent could easily confuse with this listing tool.

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 only declare readOnlyHint=false and openWorldHint=true, so the description adds real value by disclosing the confirm gate and the important fact that there is no server-side dry run — explaining why the preview exists. It falls short of describing the effect on the credential (immediate invalidation, re-auth requirement) or idempotency behavior.

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

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

Two sentences, no waste: the operation and endpoint come first, followed by the execution gate and its rationale. Every clause earns its place.

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

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

For a two-parameter mutation with no output schema, the definition covers the safety gate and the preview behavior an agent needs to call it correctly. Minor gaps remain around the effect on the session token and repeated-call behavior, which the annotations do not cover either.

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

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

Schema description coverage is 100%, so both confirm and idempotencyKey are already documented in the schema. The description reinforces confirm's semantics and adds the 'no server-side dry run' rationale, but says nothing about when to supply idempotencyKey. Baseline 3 applies when the schema carries the detail.

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

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

States a specific verb and resource ('End the dashboard session') plus the underlying endpoint POST /v1/auth/logout, which unambiguously separates it from read-oriented siblings like auth_me. It does not explicitly name auth_switchWorkspace as the contrasting session operation, but the purpose is clear on its own.

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 login-session context implies when to reach for this tool, and the confirm gate implies when the call actually executes. There is no explicit when-to-use versus alternative guidance (e.g., switching workspaces vs terminating the session) and no stated prerequisites or post-logout expectations.

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?

readOnlyHint and openWorldHint already establish this as a non-mutating external read, so the description's remaining burden is light. It nonetheless adds nothing beyond annotations: no note that it requires a valid bearer token, whether it reflects the token's scopes vs. stored user scopes, or what an error means when the session is expired.

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

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

One short sentence with the endpoint in parentheses — nothing wasted and nothing buried. It is efficient, though it is largely a restatement of the title rather than added information.

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

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

With no parameters, no output schema, and annotations covering the safety profile, the tool is simple enough that a terse description is not fatal. Still, since no output schema exists, the description is the only place that could say what the response looks like (user id, workspace id, scope array, membership records), and it only gestures at categories.

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 and the baseline is 4. The schema coverage figure is trivially 100% on an empty object.

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 what comes back (caller, workspace, scopes, memberships) and anchors it to GET /v1/auth/me, so an agent can infer this is an identity/context lookup. But it is phrased as a noun list lifted from the title rather than a verb+resource statement, and it draws no line against siblings like members_list or workspaces_create.

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 mention of calling it first to establish workspace/scope context before other calls, and no exclusion pointing to members_list for other users' data. The agent must infer the call's role from the name alone.

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

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

Annotations only say readOnlyHint=false and openWorldHint=true; the description adds the crucial client-side gate that nothing is sent unless confirm: true and that there is no server-side dry run. That is real behavioral context an agent cannot get from the annotations. It stops short of describing side effects on the current session or tokens.

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 tight sentences with the write/gate warning front-loaded after the action statement; every clause carries information. It is arguably too terse on outcomes, 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 mutation with a nested body, no output schema, and a 67% coverage rate, the definition covers the safety gate but omits permissions required, what happens to existing credentials/session state, and what the successful response contains or how the preview is shaped.

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 67% and both confirm and idempotencyKey are already documented in the schema, including the preview behavior. The description's confirm sentence largely restates the schema, and workspaceId — the required nested field — gets no additional meaning anywhere. Baseline 3.

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

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

"Switch workspace" names a specific verb and resource, and the description adds the underlying endpoint (POST /v1/auth/switch-workspace). It is clearly separable from siblings such as auth_me, auth_logout, and workspaces_create, though it never explicitly contrasts itself with them.

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

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

The confirm gate implies the calling convention (preview first, then execute), but there is no explicit when-to-use guidance, no mention of when a workspace switch is appropriate versus, say, creating a workspace via workspaces_create, and no stated 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses that this is a WRITE, that nothing is sent without confirm: true, and that there is no server-side dry run — material behavior for a mutating billing call. It stops short of stating side effects such as subscription creation or idempotency behavior.

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

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

Two tight sentences, front-loaded with the action and return value, followed by the write-safety caveat. No filler, though the parenthetical route path is of marginal value to an agent.

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 mutating, open-world billing call with a nested body and no output schema, the description covers the return value and the confirm safety requirement. It leaves gaps on what planId accepts and what the preview response contains, which matter for correct invocation.

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

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

Schema coverage is 67%: confirm and idempotencyKey are already documented in the schema, and the description mainly restates the confirm semantics. The required nested field body.planId has no explanation anywhere, and the description adds no meaning about accepted plan identifiers.

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

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

States a specific verb and resource ('Start a Stripe checkout for a plan') plus the outcome ('returns the hosted URL') and even the underlying route. It doesn't explicitly distinguish itself from billing_portal or billing_overview, 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?

The confirm gate gives a concrete execution rule and warns there is no server-side dry run, which is useful usage context. However, it offers no guidance on when to pick this over the sibling billing_overview/billing_portal tools, leaving that inference to the agent.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description's only additional behavioral signal is the '(admin)' marker, implying elevated permission is required, plus the GET verb confirming a read; it says nothing about rate limits, workspace scoping, or what the 'running charge' represents (estimate vs settled).

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 a single short line, so nothing is padded, but it is front-loaded with a duplicate of the title and then the raw HTTP path. Every token is already available in structured fields, so no sentence earns extra 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 zero-parameter read tool with no output schema, the description does list the data categories returned, which is the minimum an agent needs to judge relevance. It stops short of describing the response shape or how 'standing' and 'running charge' are computed, which matters for a billing tool where an agent may need to report numbers accurately.

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 no parameter meaning for the description to add. Schema coverage is 100% and empty, so nothing is left 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?

The description enumerates the resource's contents (plan, standing, usage against limits, running charge) and appends the endpoint, which lets an agent infer this is a read-only billing summary rather than an action. However it is a noun phrase with no verb, and it is essentially a verbatim restatement of the title, so the reader gains no framing beyond the label.

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 guidance, and no mention of the nearby billing_checkout, billing_portal, or billing_referral tools. The agent must infer from names alone that this is the read path and those are the mutation/payment 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?

Beyond readOnlyHint=false and openWorldHint=true, the description discloses the POST endpoint, the confirm:true execution gate, and the absence of a server-side dry run. These details substantially clarify execution safety, although authorization prerequisites and URL or session limitations are not covered.

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 compact statement front-loads the purpose and result, then provides the endpoint and execution safeguard. There is no filler, and the dry-run caveat earns its place.

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

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

For a simple two-parameter tool, the description covers the operation, result, endpoint, and execution guard, including return information that is absent from an output schema. It could still clarify prerequisites, whose Stripe customer is used, URL or session behavior, and when to prefer it over the other billing tools.

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

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

Schema coverage is 100%, and both confirm and idempotencyKey are already documented there. The description mostly repeats confirm's role, adding only the useful clarification that there is no server-side dry run.

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 specifies the action and resource—opening the Stripe customer portal—and states that it returns the hosted URL. It does not explicitly distinguish this flow from billing_checkout, billing_overview, or billing_referral.

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 confirm gate explains how to preview versus execute, but that is primarily invocation mechanics rather than guidance about when this flow is appropriate. No alternatives or exclusions are named, so selection among the billing siblings remains 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?

readOnlyHint=true and openWorldHint=true already tell the agent this is a safe external read, so the description's burden is lighter. It adds two useful facts beyond the annotations: the data belongs to the currently signed-in admin and it originates from a third-party service (Referalli). It says nothing about auth failure modes, rate limits, or what happens when no referral program is active.

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 a single short sentence with no padding, which is good, but the content is near-verbatim duplication of the title plus an HTTP method and path that add little decision value for an agent. The most useful phrase, 'signed-in admin', is buried mid-sentence rather than front-loaded.

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

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

For a zero-parameter, read-only lookup with no output schema, the description covers the essentials: who the data belongs to and where it comes from. However, with no output schema to describe the return shape, the description should say more about what 'link and stats' actually 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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly implies no inputs are required by framing the result as 'the signed-in admin' context, which is derived from the session rather than an argument.

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 does name the resource (the signed-in admin's partner link and stats, sourced from Referalli), so an agent knows roughly what comes back, but the verb is only implied by the parenthetical 'GET /v1/referral' and the text largely restates the title. It gives no basis for distinguishing this from adjacent billing tools such as billing_overview, billing_checkout, or billing_portal.

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 precondition stated beyond 'signed-in admin', and no mention of any alternative or exclusion. The agent must infer that this is a read-only referral-program lookup purely from the annotation set.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral detail — unset fields fall back to defaults — but says nothing about workspace scoping, permissions, or what the returned branding comprises.

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?

Extremely short and front-loaded, with the useful "defaults when unset" caveat placed early. The parenthetical path duplicates information already implied by the tool name, but the total cost is minimal.

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 annotations covering the safety profile, the definition is minimally adequate. However, with no output schema, the description should indicate what a branding payload contains (logo, colors, custom domain, etc.) so an agent knows whether the default fallback covers its need.

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 and the baseline is 4. Schema description coverage is 100% with an empty properties object, leaving no gap to compensate for.

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?

"White-label branding" restates the tool name and title, and the only specificity comes from the parenthetical HTTP path (GET /v1/branding), which implies a read. It does not explicitly state that it returns the workspace's branding configuration, nor distinguish itself from the sibling branding_set beyond the implicit get/set split.

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 and no mention of the obvious alternative, branding_set. An agent must infer the read-vs-write routing purely from the naming convention rather than from any stated condition.

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 declare readOnlyHint=false and idempotentHint=true but say nothing about execution gating; the description adds that without confirm: true no request is sent and a preview is returned, and that there is no server-side dry run. 'Replace' also signals full overwrite rather than a partial patch, which is meaningful for a 6-field required body. It could go further on reversibility or what the preview contains.

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, front-loaded with the action and the safety gate. The opening clause largely restates the title, which is minor waste, but nothing else is extraneous.

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 mutation tool with a nested object body, no output schema and full-overwrite semantics, the description covers the execute gate but leaves gaps: it does not say whether the body fully replaces all branding fields (wiping anything unset), what the preview response looks like, or what permissions/plan tier are required beyond 'admin'.

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 67%, so the baseline is 3. The description reinforces the meaning of confirm (the write gate) but adds nothing about the nested body's six required fields, their formats, or whether omitted/null values clear existing settings — those rely entirely on schema patterns and nullability.

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 ('Replace the workspace branding') plus the underlying endpoint (PUT /v1/branding) and an admin qualifier, so the agent knows exactly what is mutated. It does not explicitly distinguish itself from the sibling branding_get, but 'replace' versus read 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 description conveys the critical gate (nothing executes without confirm: true), which implicitly tells the agent when the write actually happens. It gives no guidance on when to use this versus branding_get for inspection, nor any prerequisites such as required admin role beyond the parenthetical label.

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 only declare readOnlyHint=false and openWorldHint=true; the description adds the crucial behavior that calls are simulated unless confirm is true, and that campaigns land in paused state unless status is supplied. What it does not cover is permission requirements, validation failure behavior, or what the dry-run preview returns.

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 tight sentences with the safety-critical dry-run rule placed prominently at the end. The opening sentence largely duplicates the tool title, which is minor redundancy but does no harm.

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 mutation tool with no output schema, the description covers the two things an agent could get wrong: accidental execution (dry run by default) and unexpected entity state (created paused). The remaining details are carried by a rich, mostly documented input schema.

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

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

Schema description coverage is 67%, and the description only elaborates on two things the schema already documents: the status default and confirm/idempotency semantics. The nested body fields (bid, budget, platformNative, destinationUrl) get no explanation in the description beyond inline schema text.

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 verb and resource (create a campaign on an ad account) and states the endpoint POST /v1/campaigns. The default-paused clause narrows behavior usefully, but the description never distinguishes this from siblings such as campaigns_update or campaigns_setStatus.

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-by-default rule plus 'set confirm: true to execute' is genuinely actionable guidance on how to invoke it safely. However, there is no stated when-to-use versus alternatives (e.g., campaigns_update for existing campaigns, crosspost_launch for multi-platform deployment), so routing between siblings is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds only the REST path, saying nothing about behavior when the campaign is missing, permission/workspace scoping, or response shape — modest value beyond the 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?

One sentence, front-loaded, zero padding. It is appropriately terse for a simple single-entity read, though the terseness borders on under-specification rather than optimal density.

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 (one required param, no output schema), so a short description is defensible, and the annotations carry the read-only profile. Still, for an open-world external-facing fetch, the agent gets no hint about identifier format or failure behavior.

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, but the description does show it as a path placeholder ({id}) for a campaign, which adds a small amount of meaning beyond the bare 'id: string'. It does not state whether the id is a numeric internal id, a slug, or a platform-level 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 ('Get') and resource ('one campaign'), which cleanly distinguishes retrieval of a single record from the sibling campaigns_list. The HTTP endpoint notation reinforces that this is a single-item fetch keyed by an id.

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

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

The phrase 'one campaign' implicitly contrasts with campaigns_list, but there is no explicit when-to-use guidance, no mention of what happens when the id is unknown, and no routing advice among the many campaign siblings (campaigns_update, campaigns_setStatus, campaigns_list). The agent must infer usage.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the backing endpoint (GET /v1/campaigns), which is modestly useful for debugging, but says nothing about ordering, default result limits, or pagination behavior for what is likely an unbounded list.

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 filter list comes before the endpoint annotation. Slightly dense but appropriately sized for a list endpoint.

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?

Wait—reflecting complexity: with a read-only list tool, 5 optional params, no output schema, and annotations covering safety, the description is close to sufficient, but the undocumented crossCampaignId and absent pagination note leave real gaps. Score 3 (minimum viable plus), not 4.

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 carry the load. It names four of the five filters (client, platform, ad account, status) and maps them to clear meanings, but omits crossCampaignId entirely, leaving an unexplained parameter, and gives no ID format or enum guidance 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 gives a specific verb and resource ("List campaigns") plus the four filter axes, so an agent immediately knows this is a read-many endpoint. It stops short of distinguishing itself from siblings such as campaigns_get or analytics_breakdown, which also surface campaign data.

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?

"Optionally filtered by" implies the filters can be combined or omitted, giving implicit guidance on scoped vs. bulk listing. There is no explicit statement of when to prefer campaigns_get, no note on result volume or pagination, and no exclusions.

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

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

The description discloses important behavior beyond the annotations: it is a WRITE operation and defaults to a dry run unless confirm is true. This aligns with readOnlyHint=false and adds meaningful execution context, though consequences of each status change and permission requirements are not described.

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 tight sentence with the core action and endpoint front-loaded, followed by the critical dry-run behavior. There is no unnecessary wording.

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

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

The tool has four parameters, a nested body object, and minimal annotations, but the description covers only the high-level action and dry-run semantics. It is adequate for a status-setter but leaves gaps around id semantics, status enum coverage, and the effects of destructive statuses like archived or deleted.

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 50%, with confirm and idempotencyKey already documented in the schema. The description adds some meaning by naming actions like pause, resume, and archive, but it does not explain the id parameter or fully map those actions to the enum values (active, paused, archived, deleted, pending).

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