Infinite Audience

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

Adds substantial behavior beyond the annotations: sharded uploads are analyzed against the first shard only, schema mismatch fails later with a specific error, gzip is detected from bytes and self-healed, typed 422 and 409 FILE_NOT_YET_UPLOADED errors are returned, the upload is staged with hitl:true, and discovery scope is required. These details materially help the agent understand state transitions and error handling.

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 dense but well organized and front-loaded: it starts with the trigger condition, then covers shard behavior, return shape, errors, workflow state, next steps, and required scope. Every sentence contributes operational information for a complex workflow tool.

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

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

Given the tool participates in a staged upload-to-confirmation workflow, the description covers the necessary preconditions, expected return structure, error conditions, and sequencing with sibling tools. Although an output schema exists and return details are not strictly required, the added context makes the definition complete for correct invocation.

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

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

Schema coverage is 100%, and the only parameter segment_id is already documented in the schema as the matched segment returned by create_segment(subtype=matched). The description references the same origin but adds no extra parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

States a specific action (run LLM-assisted column mapping inference) on a specific resource (an uploaded matched-segment file), and ties it directly to the create_segment(subtype=matched) upload flow. It also clearly distinguishes this analysis step from confirm_column_mappings, cancel_matched_upload, and wait_for_segment.

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 says when to call this: after uploading to the presigned URL(s) from create_segment(subtype=matched). It also states the next steps in order, including presenting results to the user, waiting, then calling confirm_column_mappings or cancel_matched_upload, and explicitly warns not to call wait_for_segment before confirm_column_mappings succeeds.

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

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

Adds real value beyond the annotations: it clarifies that composition and delivery history are preserved, so destructiveHint=true means only visibility is affected, not data loss. It also discloses the required creator scope. The scope sentence is duplicated rather than expanding into further behavior (e.g., what happens to linked campaigns).

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

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

The core behavior and effect are front-loaded, but the final two sentences repeat the same creator-scope requirement verbatim ('Requires the creator scope. Requires "creator" scope.'), which is wasted space in an otherwise short description.

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 full schema coverage, rich annotations, and an output schema, the description covers effect, reversibility, data preservation, and auth prerequisites. Only the duplicated scope line and the absence of any dependency notes (e.g., effect on campaigns) keep it from being fully 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 100%, so both parameters are already documented, and the description's note that restore=true returns the audience to active merely mirrors the schema text. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (archive) and resource (saved audience) and explains the effect: it hides the audience from the default list, with restore=true as the inverse. It does not explicitly distinguish itself from nearby siblings like patch_audience or duplicate_audience, 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?

Gives clear usage context: use it to hide an audience from the default list, and use restore=true to bring it back. It lacks explicit exclusions (e.g., 'use patch_audience instead to edit fields'), so no alternative routing guidance is provided.

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

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

Strongly exceeds the annotations: it discloses reversibility, that referencing audiences keep their composition and record count, and that a creator scope is required. The one tension is 'Always safe and fully reversible' versus destructiveHint=true — not a true contradiction since archiving does mutate state and is reversible, but the framing softens the hint rather than explaining why it is set.

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

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

The core content is well front-loaded, but the scope requirement is stated twice — 'Requires the creator scope. Requires 'creator' scope.' — which is a visible duplication artifact suggesting template concatenation. Trimming that redundancy would tighten an otherwise efficient description.

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

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

With an output schema present, the description covers everything an agent needs to call correctly: mutation semantics, reversibility, side-effect boundaries, and auth scope. Only the duplicated scope line keeps it from being fully clean.

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

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

Schema coverage is 100%, so the schema already documents both segment_id and the restore boolean. The description's 'or restore an archived one back to active' reinforces the restore semantics but adds no syntax, defaults, or constraints beyond what the schema states; baseline 3 applies.

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

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

The description pairs specific verbs (archive, restore) with a specific resource (segment) and states the exact effect: hidden from the default catalog and new audience compositions, with the inverse restore behavior spelled out. It also explicitly separates this operation from permanent deletion, so an agent can distinguish it from the destructive alternative 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?

It gives clear when-to-use guidance (archive vs. restore via the same tool) and an explicit when-not boundary by contrasting it with permanent deletion. The only shortfall is that the alternative is described conceptually rather than by a sibling tool name, so the agent isn't routed to a concrete other 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 flag destructiveHint=true, but the description supplies the specifics: adding replaces the existing segment version, completion/failure may fire webhooks, subscriptions, and opted-in email, and no matching is rerun, no charge is incurred, and no Audience is auto-created. The 'creator' scope requirement is also stated, none of which appears in 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?

Six short sentences, front-loaded with the action and the required preview step, followed by consequences. Every sentence contributes a distinct constraint or side effect; nothing is redundant with the schema or annotations.

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, open-world mutation with a nested filter object and an output schema, the description covers the prerequisite, the destructive side effect, cost/non-effects, authorization scope, and notification behavior. An agent has everything needed to call it safely without reading further docs.

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

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

Schema coverage is 100%, so parameters are already documented; the description still adds meaning by constraining target_segment_id to a 'compatible standalone' segment and framing mode as new-vs-add. It does not explain filter interaction or the idempotency key beyond what the schema states, keeping it short of the schema baseline plus full coverage.

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

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

Specific verb plus resource ('create a matched segment' / 'add unique saved identities to a compatible standalone matched segment') with both modes named. The phrase 'saved identities' and 'never reruns matching' distinguish it cleanly from create_segment, match_records, and create_audience.

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

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

Gives an explicit prerequisite workflow ('Call preview_saved_integration_segment first') and a human-in-the-loop condition ('confirm the exact counts and target with the user'). It also narrows the add_to_segment case to a 'compatible standalone' segment, telling the agent when the mode is valid.

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

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

Goes well beyond the annotations: clarifies that the destructiveHint covers only the staged upload (no file move, no status/mapping-state change), that the existing segment survives cancellation, that the call is idempotent, and that 'creator' scope is required. This resolves the ambiguity an agent would otherwise have about destructiveHint=true.

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

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

Front-loaded with the action and trigger, and every sentence carries information (behavior, alternatives, idempotency, param exclusivity, auth). Slightly dense at six sentences, but there is no filler.

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

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

An output schema exists, so return values need not be explained. Given that, the description covers everything an agent needs: trigger, side effects and non-effects, post-cancellation handling, idempotency, parameter selection, and auth scope.

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

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

Schema descriptions already cover both params, but the description adds a rule the schema does not enforce: pass exactly one of segment_id or audience_id, and that audience_id resolves server-side to the matched member segment. Useful added semantics beyond the 100%-covered 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: abort a staged matched-segment upload. Explicitly ties itself to the analyze_audience_upload workflow, making it distinguishable from generic cancel/delete siblings like archive_segment.

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

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

Names the exact trigger (user declines to proceed after reviewing analyze_audience_upload results) and routes the agent to alternatives: get_segment to inspect, archive_segment if the retained segment is no longer needed. When-to-use and when-to-use-something-else are both covered.

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 a safe read-only, idempotent operation. The description adds valuable behavioral context: the data is customer-facing, agency balances and invoices are not exposed, and parent-billed orgs see only the child's attributed usage.

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

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

The description is front-loaded with what is returned, followed by key caveats and the required scope. The first sentence is a long but necessary list; overall it is efficient with little waste.

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

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

With an output schema covering return values and annotations covering safety, the description adds the important data-exposure caveats and scope requirement. It is nearly complete, though sibling differentiation is missing.

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

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

The tool takes no parameters, so there is nothing for the description to clarify beyond the schema. Baseline score for zero parameters is 4.

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 ('Return') and resource ('customer-facing billing status') and enumerates the fields returned. It is clear what the tool does, but it does not distinguish itself from sibling tools like check_topup_status or get_account_usage.

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

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

Implies usage by describing the returned billing status and states a prerequisite ('Requires account-read scope'), but gives no explicit when-to-use guidance or alternatives versus sibling balance/usage 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 readOnly/idempotent/non-destructive, and the description adds context those fields cannot express: no charge is created, no hosted payment URL is returned, and the call requires the 'account-read' scope. The auth requirement and the explicit statement of what is NOT returned are exactly the kind of disclosure an agent needs before calling.

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

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

Four short sentences, front-loaded with the read-only constraint, then the no-URL caveat, then the ID requirement and remedy, then the scope. Every sentence carries information an agent would otherwise have to discover through failure.

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

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

With an output schema present, return values need no explanation. Given a single required parameter, annotations covering the safety profile, and this description covering provenance, fallback, scope, and what is not returned, an agent has everything needed to call it correctly or route the user elsewhere.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by clarifying provenance ('from the original top-up confirmation') and by excluding a plausible wrong input ('not an invoice/payment ID') – a disambiguation the schema's 'returned when the request was created' wording does not make explicit enough to prevent a mismatched-ID lookup.

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 ('read verified state for an existing top-up request') and immediately scopes it against write operations ('without creating a charge'). It implicitly separates itself from list-style siblings by declaring 'It cannot list top-ups', but never explicitly contrasts with the closest sibling, check_balance, so the reader must infer that boundary.

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

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

Gives explicit when-to-use (an existing top-up request whose ID you hold), explicit when-not-to-use ('cannot list top-ups'), a concrete alternative when the prerequisite is missing ('ask the account owner to review Account → Billing'), and a fallback for customer action. Nothing 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?

Beyond the destructive/openWorld annotations, it discloses the concrete side effect ('moves the staged file into place'), the blocking behavior ('nothing runs before this call succeeds'), and an auth requirement ('Requires creator scope') — all things annotations cannot convey. It also warns that the audience_id path has no inference fallback, which is real behavioral risk information.

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 purpose and the approval prerequisite are front-loaded, then the branching rules follow in order of decision. Sentences are dense with constraints rather than filler, and nothing is repeated except the ordering rule, which is reinforced for safety.

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, non-idempotent staging tool with an output schema, the description covers preconditions, ordering, scope, and branch-specific parameter rules. The one gap is retry/re-entry behavior: it does not say whether calling again after a partial failure is safe or what happens to the staged file, despite the non-idempotent and destructive hints.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra credit by adding the mutual-exclusivity constraint between segment_id and audience_id (not encoded via oneOf in the schema) and by explaining the server-side resolution of audience_id to a matched member segment. Most of the column_mappings requirements, however, are already duplicated in the schema property description rather than added 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?

Names a specific verb and resource ('Confirm column mappings for a staged matched-segment upload') and states the downstream effect ('starting identity resolution'). This distinguishes it cleanly from analyze_audience_upload (preview) and wait_for_segment (polling), so an agent can place it in the workflow without opening any schema.

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

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

Gives explicit preconditions ('Call this after analyze_audience_upload has been reviewed with the user and they approve'), explicit sequencing ('Only call wait_for_segment after this returns ok'), and an exclusivity rule ('Pass exactly one of segment_id or audience_id') with a decision rule for which branch 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 flag readOnlyHint=false, destructiveHint=true and idempotentHint=true; the description adds valuable context beyond them: it explains the mutation is an overwrite of segment.record_count via a fresh BigQuery count, and it declares the required 'discovery' scope. It does not mention query cost or rate limits for the BigQuery recount, which would matter for planning — hence 4 rather than 5. No contradiction with 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?

Four tight sentences, front-loaded with what it does and what it does not touch, followed by mechanism, return shape, alternatives, and the scope prerequisite. 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?

Given a one-param tool with an output schema, an auth scope requirement, and many sibling tools, the description is complete: it covers mechanism, mutation target, return shape, subtype breadth, and alternatives. Nothing an agent needs to call it correctly is missing.

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

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

Single parameter with 100% schema description coverage, so the schema already carries the meaning. The description adds only that the count runs over 'the segment's own definition', which is scope context rather than a new param semantic. Baseline 3 is correct.

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: refreshing the stored record_count of one saved segment, explicitly NOT its parent audience. The subtype coverage (filter, matched, similarity, propensity) further pins the scope so an agent can distinguish it from recount_audience and discovery_count without opening schemas.

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

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

Names both alternatives and the exact condition that selects each: discovery_count for unsaved population previews, recount_audience for composed audience snapshots. Use-vs-alternative routing is fully explicit.

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

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

Beyond the annotations, it discloses the required 'creator' scope, the immediate return fields, and the cardinality constraint that an audience belongs to at most one campaign. It also clarifies that record_count is only for a verified count of the exact composition.

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

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

The description is front-loaded with purpose and sibling differentiation, then moves through composition, return behavior, optional parameters, and auth scope. Despite its length, each sentence supports correct invocation or disambiguation.

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

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

Given the tool has five parameters, an output schema, and annotations, the description covers the critical creation flow, segment composition, campaign linking, return timing, and permission requirement. No material decision-making detail is missing 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 100%, so the baseline is 3. The description adds useful operational meaning around record_count and campaign_id, including omitting campaign_id to link later, though much of the per-parameter detail is already present in 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: 'Create an audience from one or more existing segments.' It also distinguishes audiences from typed cohorts and explicitly routes agents to create_segment for that separate purpose.

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 the key alternative: use create_segment for typed cohorts such as filter, matched, similarity, and propensity. It also explains when to use campaign_id versus linking later with link_audience_to_campaign.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world operation, so the safety profile is covered. The description adds genuinely new context by stating the "'creator' scope" authorization requirement and noting the new campaign object with its id is returned. It does not warn that retries create duplicates (relevant given idempotentHint=false), which is the main remaining gap.

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

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

Three short sentences with the purpose stated first, then the usage trigger, then the return value and auth requirement. Nothing is padded and no sentence is redundant with the point of being noise.

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 create with a 100% coverage schema, an output schema, and full annotations, the description covers purpose, trigger, return, and auth scope. The return-value sentence is somewhat redundant given the output schema, and there is no guidance on duplicate creation or campaign limits, so it is strong but not exhaustive.

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

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

Schema description coverage is 100% with only two flat parameters, so the schema already explains name and description fully. The description restates "optional brief and goals," which maps loosely to the description field but adds no syntax, limits, or format 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 opens with a specific verb+resource ("Create a new campaign workspace") and adds scope detail (optional brief and goals), so an agent will not confuse it with update_campaign, get_campaign, or list_campaigns. It stops short of naming any sibling explicitly, so it lands just under the top mark.

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

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

"Use when the user wants to start a new initiative, project, or campaign" gives a clear positive trigger with concrete user-intent phrasing. There is no explicit exclusion or alternative-path guidance (e.g., when to update an existing campaign instead), which keeps it from a 5.

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

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

Adds substantial context beyond annotations: async workflow behavior, pending statuses, 10–60 minute training, staged uploads with presigned URLs, token-handling warning, HITL defaults, usage-emission behavior, and creator scope requirement. These details materially help an agent understand side effects and operational sequencing.

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 long but justified by four distinct subtypes and a complex matched-upload workflow. It is front-loaded with purpose and subtype distinctions, though the single dense paragraph and repeated wait_for_segment guidance reduce readability slightly.

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

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

Given an output schema and rich annotations, the description still covers the operational gaps an agent needs: subtype-specific prerequisites, async monitoring, upload resolution sequence, HITL behavior, scope requirements, and campaign linkage. Nothing critical appears missing for correct invocation.

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

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

Schema coverage is 100%, so parameter documentation is already strong, but the description adds subtype-specific meaning: seed_description vs seed_segment_id, positive_class_segment_id, file_format/compression/shard interactions, campaign_id linkage, and create_audience behavior. It does not explain every parameter, but it adds useful 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 ("Create a segment") and immediately clarifies segment subtypes and how segments differ from audiences. The subtype-specific behavior makes it easy to distinguish from sibling tools like create_audience, count_segment, and wait_for_segment.

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 when to use each subtype and which follow-up tools to call: count_segment for filter counts, wait_for_segment for async similarity/propensity, and the analyze/confirm/cancel sequence for matched uploads. It also names the alternative actions when upload mappings are declined.

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 (destructiveHint=true, idempotentHint=false), the description discloses the cost model — no destination surcharge but base/field delivery usage still applies — and the 'creator' scope requirement, which the annotations never convey. It also states the response shape (delivery_id, status, cost, download_urls[] once completed), so an agent knows completion is asynchronous.

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

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

Six short sentences, front-loaded with the action and immediately followed by the two hard constraints (partner unavailability, the quote-first prerequisite). Every sentence carries operational information — pricing, parameter exclusivity, return values, scope — with no filler.

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

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

For a mutating, charge-incurring, open-world delivery call, the description covers prerequisites, cost behavior, scope, parameter exclusivity, and completion semantics. An output schema exists, yet the brief return summary still helps an agent plan a wait_for_delivery follow-up; nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine meaning with the template_id/field_list mutual-exclusion rule that the schema does not state. It does not explain output_format, include_unmatched, or output_compression behavior, leaving those to the (already thorough) 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?

The description opens with a specific verb and resource ('Deliver an audience as a download') and constrains the destination, so an agent knows exactly what the call produces. It does not explicitly contrast with the close sibling deliver_file_match or list_deliveries, but the audience-scoped, download-only framing still makes the target operation 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?

It gives explicit sequencing ('Call quote_delivery first: pricing depends on...') and an explicit parameter rule ('Supply template_id OR field_list — not both'). It also names when the tool will fail for reasons outside the caller's control (LiveRamp and Narrative unavailable until partner push confirms egress), which is exactly the kind of precondition an agent cannot infer.

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

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

Adds real context beyond annotations: delivery always routes to download and returns a signed URL, matched segments don't support LiveRamp/Narrative, and the 'creator' scope requirement is disclosed. It doesn't fully clarify irreversibility or what a repeated call does (idempotentHint=false), so slightly short of full marks.

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

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

Front-loaded with the core action and delivery behavior, and most sentences carry distinct routing or constraint information. A few details (backward-compatibility phrasing aside) are dense but each 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?

Given an output schema, full param coverage, and clarifying annotations, the description covers the workflow context an agent needs: what it returns, destination limits, auth scope, and param routing. Nothing critical is missing.

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

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

Schema coverage is 100%, but the description still adds value by explaining that match_id is the segment_id from create_segment (routing through an audience wrapper internally) and pointing to get_field_catalog for template_id discovery. This meaning goes beyond the 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?

States a specific verb ('Trigger download delivery') and resource ('file-based identity match job'), and explicitly distinguishes it from deliver_audience. The agent can identify exactly what the tool does without opening the schema.

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

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

Names the alternative (deliver_audience) and the exact condition that selects this tool (matched segments from create_segment(subtype=matched)). Also states exclusions (no LiveRamp/Narrative destinations) and the template_id/field_list exclusivity.

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 mark this readOnlyHint=false and destructiveHint=true, and the description explains why: with segment_id the current segment count snapshot is overwritten. That is genuinely additive context beyond the annotations. But it stops there — it never states that the snapshot overwrite is irreversible or affects what other users see, which matters for a tool flagged destructive, and it gives no cost/slowness signal beyond 'slower' on include_breakdowns.

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

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

Front-loaded with the core action and the non-persistence caveat, then a single dense sentence enumerating input modes. Every clause earns its place, though the middle sentence is long enough that a reader may skim the exclusivity constraint.

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

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

For a 9-parameter, zero-required tool with an output schema, the description covers what an agent needs: what is returned (count plus optional group_by breakdown), the input-mode exclusivity rule with its error code, the snapshot side effect, and the required 'discovery' scope. Return-value details are correctly left to the output schema.

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

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

Schema coverage is 100%, so the baseline would be 3; the description earns above baseline by stating the mutual-exclusivity rule between filters, filter_groups, segment_id, audience_id and segment_ids+set_logic, which the schema does not encode. It also names the A-minus-B role of excluded_segment_ids. It adds little on group_by or set_logic beyond what the schema already documents.

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

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

Opens with a specific verb+resource ('Preview the count for one requested population') and immediately scopes it as non-persistent ('does not create a saved audience'), which separates it from create_audience/create_segment siblings. It does not explicitly distinguish itself from count_segment or recount_audience, so an agent still has to infer that division.

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?

Clearly enumerates the five input modes and tells the agent they are mutually exclusive, including the exact failure (AMBIGUOUS_INPUT). Missing is guidance on when to use this instead of the closely named siblings count_segment or recount_audience, so the routing advice is internal to the tool rather than across 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?

Discloses traits annotations do not: cells beyond max_rows/max_cols are omitted and signalled via 'truncated', total_count vs displayed_count semantics, that grouped logic/exclusions/record limits are preserved, and the 'discovery' scope prerequisite. It does not explain why readOnlyHint is false for what reads as a query tool, leaving a small ambiguity about side effects.

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

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

Front-loaded with purpose, then return shape, then the input rule, then prerequisites – a sensible order with no filler. The return-value sentence is a long comma-separated list that is slightly dense, but every clause carries information.

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

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

Given an output schema exists, the description need not spell out return fields, yet it names the key ones and, more importantly, the truncation and preservation semantics an agent cannot infer from schema alone. Only the readOnlyHint=false tension and the absence of any sibling routing keep it from being 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 already 100%, so baseline 3 applies, but the description adds a mutual-exclusion constraint the schema does not encode as oneOf/anyOf, plus the exact rejection error AMBIGUOUS_INPUT. That is real meaning beyond the schema for a 12-parameter tool with four alternative audience inputs.

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

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

States a specific verb and resource: 'Generate a cross-tabulation pivot table across two demographic dimensions', and the required row_field/col_field confirm the shape. It never names the closest discovery siblings (discovery_count, discovery_overlap) or get_segment_demographics, so the agent must infer which of several demographic-reporting tools this is.

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 'EXACTLY ONE of ... (more than one is rejected with AMBIGUOUS_INPUT)' rule is genuinely useful selection guidance for how to build the audience. But there is no statement of when to pick a crosstab over a plain count or a single-dimension demographic breakdown, which are exactly the choices the sibling list presents.

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

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

The description adds substantial context beyond the annotations: the 'discovery' scope requirement (an auth prerequisite), the masked nature of returned rows, the mutual-exclusion rejection with a named error code, and the fact that saved compositions/exclusions are preserved and excluded segment previews are not persisted. One unresolved tension: annotations declare readOnlyHint=false and idempotentHint=false, which imply state changes/side effects (e.g. metered queries) that the read-like 'return sample rows' framing does not explain.

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 output/scope statement is front-loaded, followed by the accepted input modes and the exclusivity rule. It is dense but nearly every clause carries operative information (error code, exclusion semantics, scope); it could be tightened marginally but wastes 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?

With an output schema handling return values and full schema coverage on inputs, the description covers what structured fields cannot: auth scope, mutual-exclusion behavior, masking, and composition preservation. It is complete enough to invoke correctly, with only the readOnlyHint=false side-effect ambiguity left unaddressed.

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

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

Schema coverage is 100%, so every parameter, including nested filter operators and BETWEEN/LIKE semantics, is already documented in the schema. The description adds only the higher-level mutual-exclusion rule and the 'A minus B' semantics of excluded_segment_ids, so the schema does most of the work and 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: "Return up to 25 masked sample rows for audience matching criteria," and enumerates the accepted input modes (filters, segment_id, audience_id, segment_ids+set_logic, filter_groups). It is clear what the tool produces. It does not, however, distinguish itself from the sibling discovery_count/discovery_crosstab/discovery_overlap tools, so an agent must infer that this is the row-preview variant.

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?

"All inputs are mutually exclusive — providing more than one is rejected with AMBIGUOUS_INPUT" gives real selection guidance among the input modes, and the excluded_segment_ids clause describes an ad-hoc preview path. But there is no explicit guidance on when to use this tool versus discovery_count or discovery_crosstab/the other discovery siblings, so usage 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false): it discloses the 'discovery' scope requirement, states that saved composition/exclusions/record limits are preserved, warns that empty optional distributions mean unavailable not zero, and documents the AMBIGUOUS_INPUT rejection. Minor gap: it doesn't clarify why readOnlyHint is false for what reads as a compute call.

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

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

Front-loads purpose and return fields, then input constraints, then scope. Dense but every sentence carries real rules; the one slightly wasteful bit is listing the return fields despite an output schema existing.

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 deeply nested tool with an output schema and annotations, the description covers the key gotchas an agent needs: one-input-per-side, ambiguity rejection, preserved composition, empty-distribution semantics, legacy parameters, and auth scope. Nothing materially missing 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?

On top of 100% schema coverage, it adds the crucial 'EXACTLY ONE of' constraint per side that the schema cannot express with its current shape, and explains the audience_id_a/audience_id_b legacy alternates and their mutual exclusivity with a/b. Clear value 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 ('Calculate') and resource ('overlap between two audience criteria sets'), which is inherently distinguishable from siblings like discovery_count, discovery_crosstab, and discovery_lookup. However, it never names or contrasts those siblings, so the agent must infer which discovery tool to pick.

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

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

The description notes the required 'discovery' scope and the mutual-exclusivity rule for the legacy parameters, which implies when to use the modern a/b shape. But it never says when to choose this tool over discovery_crosstab or discovery_count, so usage is only implied.

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

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

Beyond the annotations, the description discloses important behavior: lineage tracking with parent_audience_id and derived_from, pinned segment versions, copied composition, immediate active status, null record_count, optional campaign linkage, and the required 'creator' scope. These details add substantial operational context not already present in the structured fields.

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

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

The description is front-loaded with the core action, then efficiently covers lineage, copied composition, initial state, recount behavior, campaign linkage, and scope. The density is justified by the complexity of the operation.

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

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

Given the presence of annotations and an output schema, the description supplies everything an agent needs to call this tool correctly: authorization scope, resulting-object behavior, lineage semantics, initial record_count state, and the need to call recount_audience for a fresh count.

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

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

Schema description coverage is 100%, so the input schema already documents audience_id, name, and campaign_id fully. The description reinforces campaign linkage and the source-audience concept, but does not add meaningful parameter-level detail beyond what the schema already provides.

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

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

The description names a specific verb and resource: duplicate an existing audience. It also states the resulting object's lineage, composition, active state, and initial record_count, which clearly distinguishes it from create_audience and other sibling 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?

The description makes the use case clear: duplicate an existing audience, optionally link it to a campaign, and call recount_audience when a fresh count is needed. It does not explicitly name alternatives such as create_audience or duplicate_segment, so it is strong but not fully exhaustive on when-not-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 declare the generic profile (not read-only, not destructive, not idempotent); the description adds substantial context beyond that — what is preserved per subtype, that computed data is referenced rather than recomputed, lineage fields recorded, the null record_count side effect, two distinct 409 error codes, and the required scope. That is exactly the kind of behavior an agent cannot get from annotations.

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

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

Front-loaded with purpose, then behavior, then failure modes and permissions — a sensible order. The subtype enumeration is dense but each clause carries real information; still, the sentence is long enough that trimming would improve scannability.

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

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

An output schema exists, so return shape need not be explained, and the description covers the remaining pieces an agent needs: preserved data per subtype, lineage side effects, count semantics, permission requirement, and specific error conditions. Nothing material is missing for a 2-parameter tool.

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

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

Schema coverage is 100%, and the schema itself documents the name default ("<source name> (copy)") and segment_id. The description adds no parameter-level syntax or format meaning beyond implying segment_id identifies the source, 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?

States a specific verb and resource ("Create a duplicate of an existing segment") and immediately scopes it by enumerating what is carried over per subtype. An agent can distinguish this from create_segment because duplication semantics (preserved subtype data, lineage) are spelled out.

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

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

Explicitly routes to a sibling: "Filter duplicates start with record_count null — trigger a recount with count_segment for a fresh count." It also gives the preconditions under which the call will fail (unavailable match data, pending/failed source) and the required 'creator' scope. It stops short of explicitly contrasting duplicate_segment with create_segment, which is the only gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description still adds genuinely new behavioral facts beyond them: it requires the 'account-read' scope and it explicitly reassures the agent that calling it will not create a charge or modify the account, which matters for a billing-adjacent tool.

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

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

One dense sentence enumerating the payload, followed by a non-mutation guarantee and the scope requirement. No filler, and the key content is front-loaded.

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

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

An output schema exists, so enumerating return fields in the description is partly redundant, but it usefully helps selection. Auth scope and non-mutation semantics are covered; only the relationship to sibling billing tools is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The description correctly implies the org context is implicit rather than passed in.

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 ('Read') and resource ('this organization's usage') and enumerates the exact metrics returned: segment/audience totals, 30-day delivery count, rated spend in cents, projection freshness, compute-ceiling percentage. That specificity makes it hard to confuse with the write/mutation siblings, though it never names the adjacent billing siblings (check_balance, check_topup_status) 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 is only implied by the read-only framing and the scope requirement; there is no explicit 'use this when you need X instead of check_balance/check_topup_status' routing. An agent can infer it is the aggregate usage snapshot, but the choice among billing-related tools 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 idempotent/non-destructive/non-open-world, and the description adds a genuinely useful auth requirement ('Requires discovery scope'). However, it never explains the notable annotation quirk that this 'Get' tool is marked readOnlyHint=false, nor what the 'rerun' wording implies about side effects. With annotations present the bar is lower, but that gap is material for a tool that may mutate state.

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

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

Three short sentences, front-loaded with the resource and payload contents, followed by usage and auth. Nothing is repeated, though 'reload, inspect, or rerun' is a slightly loose triple that pads the usage cue without sharpening it.

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?

Low-complexity getter with one param described in full and an output schema that already covers return values, so the description needn't restate them. The scope requirement and payload summary make it callable without guesswork; only sibling routing against get_audience_demographics/get_segment_audiences is left unstated.

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

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

The single audience_id parameter has 100% schema description coverage, including its provenance ('returned by list_audiences or create_audience'). The description adds only 'a specific saved audience', so the schema does essentially all the work — baseline 3 applies.

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

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

States a specific verb+resource ('Get customer-facing details of an audience') and adds what the payload contains (expanded segment summaries and composition), which goes beyond the bare name. It doesn't differentiate itself from near-neighbors like get_audience_demographics, get_segment_audiences, or list_audiences, so it falls short of 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?

Provides an implied usage cue ('when the user wants to reload, inspect, or rerun a specific saved audience'), which is more than nothing. But it names no alternative and gives no when-not guidance — an agent can't tell from this text whether to call get_audience, list_audiences, or refresh_audience for a given request.

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

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

Goes beyond the annotations by disclosing the auth requirement ('discovery' scope), the backend that computes the data (BigQuery), and a 20-minute server-side cache – all behaviorally relevant. The caching note is also useful given the annotations declare idempotentHint=false and readOnlyHint=false for what reads as a query operation, though the description never explicitly asserts a write, so this is not a direct contradiction.

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

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

Three sentences, each earning its place: what it does, what it returns, then operational constraints (cache, scope). Purpose is front-loaded and nothing is redundant.

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

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

With an output schema present, return-value detail is not the description's job, and it covers the important gaps (scope, caching, computation source). The only missing piece is routing guidance versus the segment-demographics sibling, which matters for an agent choosing among many demographic/count tools.

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

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

Schema description coverage is 100% and the single audience_id parameter is fully documented there, so baseline 3 applies. The description adds no syntax, format, or case-sensitivity hints for the ID beyond what the schema provides.

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

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

States a specific verb+resource ('Profile a saved audience composition') and enumerates the returned metrics, so it is clearly distinguished from a generic fetch. It does not explicitly name the segment-oriented sibling get_segment_demographics as the alternative, so 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?

The description supplies a prerequisite ('Requires discovery scope') but gives no explicit when-to-use guidance and does not point to alternatives such as get_segment_demographics or count_segment. Usage must be inferred from the resource name.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real value on top: the required 'discovery' scope and the caveat that linked segments are summaries rather than full definitions. It stops short of covering error behavior for a missing campaign_id, which keeps it from a 5.

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

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

Three short sentences, front-loaded with the core purpose, then usage conditions, then the sibling handoff and scope requirement. No filler or redundancy.

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

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

An output schema exists so return values need not be spelled out, yet the description still orients the agent to brief and audience content. Hot path, sibling escape hatch, and auth scope are all covered for a one-parameter read tool.

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

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

Schema description coverage is 100% for the single campaign_id parameter, so the schema already carries the semantics. The description adds no format or sourcing hints for the ID beyond what the schema states, making the baseline 3 appropriate.

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

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

Specific verb (retrieve) plus resource (campaign) plus the contents returned (brief and linked audience summaries). It is clearly distinguishable from list_campaigns, create_campaign, update_campaign, and from get_segment, which it explicitly routes to for deeper segment detail.

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

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

States explicitly when to use it (user asks about a specific campaign or wants its audiences) and names the alternative tool with the condition that selects it: get_segment for filter_groups definitions. It also sets expectations that linked segments are only summaries.

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

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

The description frames this purely as a read ('Return the platform current data-release version'), yet annotations declare readOnlyHint=false and idempotentHint=false without the description reconciling that. The description does add genuine behavioral context (discovery-scope requirement, and how the value is interpreted against resolution_action), but the unreconciled read/write signal is a real inconsistency an agent could act on.

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

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

Two sentences, with the purpose front-loaded before the usage explanation. The second sentence is somewhat convoluted (nested quotes, long clause) but every element carries information; nothing is filler.

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

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

An output schema exists, so return-value documentation is not required. The description still supplies the two field names, the scope prerequisite, and the interpretive rule tying the result to match_records. The main gap is not addressing the non-read-only annotation, which an agent would want clarified for a simple getter.

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

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

There are zero input parameters, so the baseline is 4. The description correctly introduces no parameter discussion and instead directs attention to the response fields (current_release_major/minor), which is the right focus for a no-arg tool.

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: 'Return the platform current data-release version (current_release_major/minor).' It also names the related sibling, match_records, so the agent can place it in a workflow. It stops short of explicitly contrasting with other getter/list tools (get_match_run, get_workflow_status), but the resource 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 says concretely when to reach for it: compare its value against a match_records result's resolution_action to interpret 'current' vs 'refreshed'. It also states the prerequisite ('Requires discovery scope'). It does not state any exclusion or what to do instead if the scope is missing, which keeps it out of 5 territory.

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, idempotentHint, and destructiveHint=false, the description explains important return behavior: fresh 24-hour download_urls[] while the artifact is retained, and that expires_at is artifact retention rather than signed-link expiry. It also discloses the required 'discovery' scope, adding auth context not conveyed by annotations.

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

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

The description is front-loaded with the core action, then adds the most important return caveat, the polling use case, and auth requirement. Every sentence contributes distinct, useful information with no repetition.

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

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

An output schema exists, annotations cover safety and idempotency, and schema coverage is complete. The description fills the remaining gaps by explaining polling usage, download URL freshness, retention semantics, and required scope.

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

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

Schema description coverage is 100% and both parameters are already documented in the schema. The description does not add parameter syntax or format details beyond what the schema provides, so it meets the baseline for fully covered parameters.

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

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

The description states a specific verb and resource: 'Get status and details of a single delivery.' It distinguishes itself from list-oriented siblings by emphasizing 'single delivery' and from deliver_audience by describing polling after delivery creation. It does not explicitly contrast with wait_for_delivery, which is the closest sibling alternative.

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

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

The description gives clear usage context: 'Use this to poll status after deliver_audience returns status: processing.' It also states the required 'discovery' scope. However, it does not mention when to prefer wait_for_delivery or how this differs from list_deliveries for multiple deliveries.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds meaningful operational context beyond that: bounded pagination, default filterable-audience scope, enrichment-only feature_store fields, opt-in pricing, and required discovery scope. There is no contradiction with 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?

The description is front-loaded and information-dense, covering the most important defaults and cursor flow early. It is slightly repetitive, especially the duplicated statement that the tool requires discovery scope, which prevents a perfect conciseness score.

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 10 optional parameters, an output schema, and clear annotations; the description covers pagination, default filtering, enrichment mode, pricing opt-in, and scope requirements. An agent has enough context to invoke and paginate correctly without needing return-value details the output schema already provides.

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

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

Schema coverage is 100%, so parameter meanings are already largely documented. The description still adds useful semantics, including zip_code alias handling, state two-letter/full-name inputs, purpose default behavior, and value_cursor usage, though it leaves several parameters to the schema.

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

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

The description states a specific verb and resource: discovering a bounded page of catalog fields, including aliases, operators, coded values, and coverage. It is clear what the tool does, but it does not explicitly distinguish itself from related discovery siblings such as discovery_lookup.

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 concrete usage guidance: use purpose=enrichment for output fields, follow next_cursor for more fields, pass field_name plus values_next_cursor for more enum values, and opt in to pricing. It does not state when to use this tool instead of sibling discovery tools, so the alternative-tool guidance is incomplete.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. Beyond that, the description adds substantial behavioral context: amount_charged is null until a successful delivery participation, audience_status reflects whether the linked audience remains open-able in Library, and mapping_warnings should be reported to the user. It also discloses the required scope, which is important for invocation.

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

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

The description is front-loaded with the core action and is organized around usage, return details, and caveats. It is somewhat dense because it lists many return fields even though an output schema exists, but most of the extra text earns its place through semantic caveats like amount_charged and mapping_warnings.

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

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

Given the presence of an output schema and strong annotations, the description is complete enough for correct invocation. It covers purpose, usage contexts, important return-field semantics, warnings interpretation, and required scope. Nothing critical appears to be missing for an agent deciding whether and how to call this tool.

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

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

Schema coverage is 100%, and the match_id parameter is already well documented in the schema. The description adds useful equivalency information by clarifying that match_id is the segment_id and that it is returned by create_segment(subtype=matched) or list_file_match_jobs. This meaningfully augments the already-complete schema without being redundant.

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

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

The description uses a specific verb and resource: it retrieves a single file-based identity resolution job by match_id. It clearly distinguishes this from the list operation by saying 'single' and by explaining that match_id is the segment_id. An agent can identify exactly what this tool does without inspecting the schema.

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

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

It gives clear usage contexts: checking job progress after create_segment(subtype=matched) and retrieving audience_id for delivery. It also states the required 'discovery' scope. However, it does not explicitly compare this with list_file_match_jobs or state when not to use 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuine behavioral context: the run must be a 'retained' run, the payload is 'customer-safe provenance' with 'intermediate workflow artifacts... not exposed', and a 'discovery' scope is required. That is meaningful disclosure beyond the annotation set, though nothing is said about behavior when the run is missing or 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?

Three tight sentences ordered purpose, return shape, then usage and prerequisite. No filler, and the core action is front-loaded in the first clause.

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

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

Output schema exists, so the description does not need to enumerate return fields, yet it still characterizes the payload and explicitly notes what is excluded. Combined with the ID source and scope requirement, an agent has everything needed to invoke 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?

With a single parameter at 100% schema coverage, the schema already carries the full meaning of run_id including its source. The description's 'by run_id' and the list_integration_runs pointer duplicate rather than extend that, so baseline 3 applies.

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

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

States a specific verb and resource ('Get one retained integration run by run_id') and immediately scopes it against the sibling list_integration_runs. An agent can tell this single-record fetch apart from the list operation without inspecting the schema.

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

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

'Use an ID from list_integration_runs' gives the explicit sourcing rule and 'Requires discovery scope' states an auth prerequisite. It stops short of ruling out lookalike siblings such as get_workflow_status or get_match_run, which is the only missing piece.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds useful behavioral context beyond annotations by stating the required 'discovery' scope and clarifying that amount_charged is a conservative pending-usage estimate rather than a finalized invoice amount; it does not describe error behavior, but that is a minor gap for this simple read.

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 two compact sentences, front-loading the action and then the returned details and scope requirement. Every clause provides useful information with no filler.

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

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

For a simple read tool with an output schema and full annotations, the description covers the key missing context: required scope and the caveat around amount_charged. The only notable omission is an explicit statement of how it relates to list_match_runs and match_records as alternatives, but the schema makes that relationship inferable.

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

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

Schema description coverage is 100%, and the run_id parameter is fully documented as coming from list_match_runs or a prior match_records call. The description only restates 'by its run_id' and adds no syntax, format, or further semantic detail 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 uses a specific verb ('Retrieve') and resource ('single micro-batch match run by its run_id'). The word 'single' distinguishes it from list_match_runs, and the schema's run_id description ties it to list_match_runs and match_records, so an agent can identify its role without opening those 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?

The description implies it is used after obtaining a run_id from list_match_runs or match_records and states the required 'discovery' scope, but it does not explicitly say when to choose this tool over siblings or when not to use it. Usage is therefore inferable rather than spelled out.

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

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

Beyond the readOnly/idempotent annotations, it discloses the required 'discovery' scope and what the call yields (aggregate progress/status plus the durable segment ID once complete). It does not describe what a partial/incomplete status looks like or whether repeated polling is expected, which would have pushed it higher.

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: the identification/precondition comes first, the return contract and the negative constraint follow. Every clause carries information an agent would otherwise have to infer.

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

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

With an output schema present, return values need not be spelled out, and the description still summarizes them; the scope requirement is a useful addition. It leaves minor gaps around polling behavior and the status vocabulary for a long-running check, but nothing essential 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 100% and the schema already explains that materialization_id comes from build_saved_integration_segment, so the description's restatement adds little. Baseline 3 is appropriate for a single fully-documented parameter.

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

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

States a specific verb and resource — check a saved-match segment materialization by materialization_id — and explicitly disambiguates from build_saved_integration_segment by noting it does not start another build. An agent can distinguish it from the build sibling without opening either schema.

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

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

"after build_saved_integration_segment" gives a clear precondition for when to call it, and "it does not start another build" excludes the most likely misuse. There is no explicit mention of polling cadence or of an alternative (e.g. wait_for_segment-style blocking helper), so it stops short of full when/when-not 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?

The description presents a pure read operation ('Fetch', 'inspect'), while annotations declare readOnlyHint=false, indicating the tool is not read-only. That is a direct contradiction; although scope and return-shape context are provided, the annotation conflict dominates the behavioral assessment.

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

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

The description is front-loaded with the core action and then adds return-shape and scope details. It is somewhat long for a one-parameter read tool, especially since an output schema exists, but the sentences are purposeful.

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?

It covers the required parameter, return content, and auth scope, and an output schema exists. However, it does not address the non-read-only behavior implied by readOnlyHint=false, leaving a meaningful behavioral gap.

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

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

Schema coverage is 100%, and the single segment_id parameter is fully documented in the schema. The description says the segment is fetched 'by segment_id' but adds no format or constraint details beyond the schema, so the baseline 3 applies.

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

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

The description uses a specific verb and resource: 'Fetch one segment by segment_id.' It also clarifies the scope by saying one segment is retrieved, which naturally distinguishes this from list_segments and related mutation 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 gives a clear positive use case: 'Use to inspect a definition before modifying or composing it,' and notes the required 'discovery' scope. It does not explicitly name when not to use it or point to specific alternatives such as list_segments or patch_segment.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new context beyond annotations: the required 'discovery' scope (an auth prerequisite the agent cannot infer elsewhere) and the downstream-impact purpose. It stops short of noting volume/limits on large segment fan-out.

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

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

Front-loaded with purpose, then return shape, then usage triggers and the scope requirement — no wasted sentences. The enumeration of return fields is mildly redundant given an output schema exists, but it is compact and easy to scan.

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

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

With a rich annotation set and an output schema, the description only needs to add purpose, usage triggers, and prerequisites — all of which it supplies, including the 'discovery' scope. Nothing an agent needs to select or call this tool correctly is missing.

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

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

Single parameter with 100% schema description coverage, so the schema already explains segment_id. The description adds no format, lookup, or edge-case guidance (e.g., what happens for an unknown segment ID) beyond the schema 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 ('List every audience that references a segment') with explicit scope ('every') plus campaign linkage, which distinguishes it from siblings like get_segment or list_audiences. An agent knows exactly what it returns 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?

Gives concrete triggering scenarios: before archiving, refreshing, or editing a segment, or when the user asks where a segment is used across campaigns. That implicitly points at siblings such as archive_segment and refresh_segment, though it never explicitly names alternatives or states when not to use it.

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

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

Adds context beyond the annotations: server-side caching for 20 minutes, the required 'discovery' scope, and that non-filter subtypes resolve through the same ID-set composition used by audiences. This is useful operational detail. It does not, however, explain why annotations mark the tool as non-read-only and non-idempotent (presumably BigQuery job cost), leaving a small gap between declared hints and described 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?

Front-loads the core scope in the first sentence and keeps the remainder dense with substantive detail. Minor redundancy: 'without any audience set logic or exclusions' and 'no audience composition (set_logic/exclusions) applied' restate the same exclusion twice.

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

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

With an output schema present, the description needn't enumerate return fields, yet it still summarizes them (age buckets, geography, optional behavioral/financial extra). Combined with caching, scope, and subtype handling, an agent has everything needed to call this correctly.

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

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

There is only one parameter and schema description coverage is 100%, so the schema already fully documents segment_id. The description adds no format, sourcing, or validation detail about the ID, so baseline 3 applies.

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

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

States a specific verb and resource ('Profile one saved segment') and pins down the scope precisely: demographics computed over the segment's own definition with no audience composition. The contrast with the audience-level path implicitly separates it from siblings like get_audience_demographics and get_segment.

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?

Makes clear this is the segment-level path with no set_logic/exclusions applied, which tells an agent when to pick it over an audience-composition tool, and it notes applicability to all subtypes (filter, matched, similarity, propensity). It stops short of naming the alternative sibling explicitly ('use get_audience_demographics instead when...'), so a 4 rather than a 5.

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

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

The description describes a read-only inspection operation ('Check the current status'), but annotations declare readOnlyHint=false and destructiveHint=true. This is a direct contradiction, so the behavioral transparency score is forced to 1 despite the description otherwise disclosing return fields and scope 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 written sentences, front-loaded with the core purpose and followed by return-value and auth details. Every sentence contributes useful information without redundancy.

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

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

The description covers what the tool returns, failure behavior, and required scope, which is strong for a status tool. It could better route the agent to respond_to_workflow_gate when paused_gate is present, but with an output schema available the omission is minor.

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

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

There is one parameter with 100% schema description coverage, including its origin from create_segment(subtype=similarity/propensity). The description adds no syntax or format detail beyond the 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: checking status, step, and gate info for a running similarity or propensity segment workflow. It distinguishes itself from siblings such as wait_for_workflow and respond_to_workflow_gate by focusing on inspection rather than blocking or decision-making.

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

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

It gives clear context (running similarity or propensity workflows) and mentions paused_gate when awaiting a decision, implying usage. However, it does not explicitly say to use respond_to_workflow_gate when a gate is paused or wait_for_workflow when blocking is desired, so alternatives are left implicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description reinforces the idempotency while adding genuinely new context: the exclusive-membership constraint, the AUDIENCE_ALREADY_LINKED error code with the current_campaign_id it returns, and the 'creator' scope requirement. It does not explain why the operation is flagged destructive, which would be the last missing piece.

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

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

Four short sentences with the core action and cardinality rule front-loaded, followed by idempotency, error handling, and auth. Every sentence carries information, though the idempotency clause partially restates the idempotentHint annotation.

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

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

An output schema exists, so return values need not be described. With auth scope, failure code, exclusivity constraint, and idempotency all covered, an agent has everything needed to invoke this correctly and interpret the likely error.

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

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

Schema description coverage is 100% for both required parameters, so the schema already explains audience_id and campaign_id. The description adds no format, syntax, or lookup guidance beyond the IDs themselves, so baseline 3 applies.

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

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

A specific verb+resource ('Link an existing audience to a campaign') in the first sentence, immediately narrowed by the cardinality rule 'Each audience can belong to at most one campaign'. That rule distinguishes it functionally from the sibling unlink_audience_from_campaign and from create_audience.

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 the precondition for success and what to do when it fails: 'unlink it there first' when the audience is already in a different campaign. It also tells the agent that repeat calls are safe, which removes a common hesitation. It stops short of naming the unlink sibling tool explicitly, leaving the agent to infer it.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds genuinely new context: pagination exists, signed download links are omitted from responses, and a 'discovery' scope is required. It stops short of describing rate limits or link expiry, but the auth and output caveats are the ones an agent would otherwise trip on.

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 scope statement and the alternative routing are front-loaded in a compact sequence of sentences, and each carries information. Minor deduction for the run-on comma splice ('filters, Use audience_id') that slightly muddles the transition.

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