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

Annotations only signal readOnly=false, openWorld=true, idempotent=false, destructive=false. The description goes well beyond that by disclosing dry-run-by-default, no money spent, created-paused behavior, CPA model/rate 0 defaults, global payout rule creation, and the tracking-link derivation logic. It also explains that the response echoes exactly what was created, which is important given there is no output schema.

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

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

The description is long but information-dense, and it is well structured with a front-loaded summary followed by defaults, tracking-link behavior, execution mode, and safety notes. There is minor redundancy — 'created paused' appears twice and payout-rule behavior is repeated in the schema — but nearly every sentence earns its place.

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

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

For a complex create tool with no output schema, the description covers prerequisites, defaults, side effects, dry-run vs confirm semantics, activation requirement, geo scoping, and the result format. An agent has everything needed to call it correctly and predict the outcome, including whether money is spent.

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, but the description adds real value on top of the schema: it explains why user_email is required, how zone_id behaves with zero/one/many zones, that confirm=false means dry-run, and cross-parameter implications like payout creating a global payout rule and geo only affecting /serve rotation. This is far more than a restatement of schema fields.

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

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

The description opens with a specific verb and resource: 'Create a campaign (offer) in the current namespace from a compact spec'. It also clarifies what the tool is not (it does not create team members, it references create_team_member) and lists the concrete inputs, so an agent can distinguish it from sibling tools 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?

The description gives strong usage context: the advertiser must already exist as a team member, create_team_member is the fallback, zone selection is automatic when exactly one zone exists, and confirm=true is needed to leave dry-run mode. It does not explicitly contrast this tool with update_campaign or set_campaign_status, but the creation flow is clear enough that the missing exclusion is minor.

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?

Description reveals critical behaviors beyond annotations: plaintext API key returned only once, no invite email sent, dry-run mode, and API-enforced role overrides. This far exceeds the minimal safety profile indicated by readOnlyHint=false.

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 and front-loaded with the core action. While every sentence adds value, minor redundancy could be trimmed. Overall, it is well-structured for an agent to parse quickly.

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 complexity (6 parameters, no output schema), the description covers prerequisites, return value, dry-run behavior, and security notes. Missing details on error handling or duplicate emails, but sufficient for most agent use.

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 baseline is 3. The description adds value by explaining interactions (e.g., manager_email overridden for scoped managers) and dry-run context, elevating it above baseline but not fully exploring all 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?

Description clearly states 'Invite a team member: create a user API key with an email in the current namespace' and equates it to the dashboard's 'Add Team Member', making the action and resource unambiguous. It distinguishes itself from sibling tools like list_team and delete_payout_rule by focusing on creation.

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?

Description explicitly states required roles and their limitations, including how scoped manager roles override inputs. It also clarifies the default dry-run behavior and the need for confirm=true to apply, providing clear when-to-use guidance.

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

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

Beyond the annotations, it discloses the critical dry-run default ('DRY-RUN by default; pass confirm=true to apply'), write-only storage of api_token for 'upcoming cost sync,' and preset copy behavior with editable rows. These are exactly the behavioral traits that affect whether an agent mutates data without realizing it.

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?

Five dense sentences, all high-signal and front-loaded with the core purpose before workflow and safety details. No filler or repetition of schema text; each clause earns its place.

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

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

For a 7-parameter creation tool with no output schema, the description covers the full lifecycle: preset usage, template editing, zone linking, URL rendering, API token storage, and the dry-run/confirm behavior. The absence of an output schema is mitigated by the explicit confirmation gate, so an agent has everything needed to invoke 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 coverage is 100%, so the schema carries most parameter meaning. The description still adds value by explaining how preset populates tracking/postback templates and by defining [BRACKETED] pieces as account-specific placeholders, which helps an agent fill postback_template or tracking_template correctly.

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 ('Create a traffic source') and immediately clarifies what that resource is: 'an ad network account bought from.' It also distinguishes the creation workflow from related tools by pointing to create_zone/update_zone and get_zone_url, making the tool's role clear relative to siblings.

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

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

It provides clear when-to-use context: create by choosing a preset or omitting it for a custom source, then link zones and render templates via the named sibling tools. It does not explicitly state when update_traffic_source or list_traffic_sources should be used instead, so there is no formal exclusion, but the intended flow is evident.

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

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

The description discloses critical behaviors not visible in annotations: DRY-RUN by default, confirm=true required to apply, status always active on create, and the plan's zone limit error (402). These are valuable operational details that exceed what annotations provide.

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 dense sentences that front-load the purpose, then list required/optional parameters, then state the most important behavioral facts. No wasted words; every sentence earns its place.

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

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

For a 7-parameter creation tool with no output schema, the description covers the required input, key optional parameters, default dry-run behavior, confirmation requirement, resulting status, and quota error. This is sufficient for an agent to invoke it safely and 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 coverage is 100%, so the schema already documents every parameter. The description mostly restates the optional parameters and adds minor context like postback_url being for conversions and traffic_source_id influencing get_zone_url, but it does not significantly add meaning 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 names a specific verb and resource: 'Create a traffic-source zone in the current namespace.' It clearly distinguishes this from sibling tools like update_zone, list_zones, and create_campaign by specifying the resource type and scope.

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 context: creating a new zone, requiring a name, and linking an optional traffic source. It does not explicitly state when not to use it or mention alternatives, but the context is enough for an agent to select it over update_zone or create_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?

The description discloses the destructive nature (blacklist modification), the dry-run default, the AND logic for thresholds, and the significance guard (min_clicks). Annotations already indicate destructiveHint=true, so the description adds context on how the destruction works (adding to blacklist) and the evaluation window. No contradictions.

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 concise: four sentences that front-load the purpose and key behaviors (dry-run, confirm, threshold logic). No unnecessary words, and every sentence adds essential information. The structure is clear and easy to parse.

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

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

Given the tool has 9 parameters and no output schema, the description covers the core behavior well: evaluation window, threshold criteria, dry-run vs confirm, and the significance guard. It could mention what the response looks like (e.g., list of zones to be cut) or error cases (e.g., invalid campaign). Still, it provides enough context for most use cases.

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 described. The description adds value by clarifying that 'spend' means media_cost, explaining the AND logic for multiple thresholds, and noting that range is ignored if from/to are given. This extra context helps the agent understand parameter interactions 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 clearly states the tool's purpose: blacklisting underperforming zones based on thresholds. The verb 'cut' and resource 'zones' are specific. It distinguishes from sibling tools like list_zones, update_zone, or remove_targeting_rule by focusing on automated performance-based blacklisting with dry-run and confirm modes.

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 explains when to use the tool (to cut underperforming zones), how to use it (dry-run first, then confirm), the logic of threshold matching (ALL conditions), and defines key terms like 'spend'. However, it does not explicitly state when not to use it or contrast with alternatives like manual editing via update_zone.

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 indicate destructiveHint=true but description adds the dry-run behavior (preview before applying) and the fallback to $0 if no global rule exists. This provides behavioral context beyond the annotations.

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

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

Two sentences cover the purpose, two modes, dry-run behavior, and consequences. No extraneous words; every sentence adds value.

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

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

Given the tool's complexity (deletion with two modes, dry-run, fallback), the description covers all essential aspects. No output schema exists, but return values are not critical for operation. Sibling tools like set_payout_rule provide contrast.

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 has 100% coverage, but description adds meaning: it explains the interaction of zone_id with global vs per-zone deletion, and the role of the confirm parameter in applying changes. This clarifies parameter usage beyond the schema descriptions.

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?

Description starts with 'Delete a campaign payout rule (global or per-zone)', clearly specifying the verb and resource. It distinguishes two modes of operation and mentions the consequence of no rule remaining ($0 conversions), making the purpose 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?

Explicitly states when to omit zone_id (delete global rule) vs when to pass zone UUID (delete zone override). Also explains the dry-run default and the need for confirm=true to apply, giving clear usage instructions.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so safety is clear. The description adds behavioral context about what the tool returns: untruncated offer URL, exact schedule, budgets/pacing, silent-conversions flag, payout goal type, and targeting/payout rules. This enriches beyond annotations without 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?

The description is two sentences: the first enumerates the full record contents, the second provides usage context and alternatives. Every word earns its place, is front-loaded with the purpose, and is extremely concise.

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

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

For a simple read-only tool with one parameter and no output schema, the description fully covers what the tool does, what data it returns, and when to use it. Given the complexity, it is complete and leaves no necessary gaps.

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

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

The schema covers campaign_id with 'Campaign id to fetch' and is 100% documented, so the baseline is 3. The description does not add parameter-specific semantics, but given the parameter is self-explanatory and there is only one, no further elaboration is necessary.

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 'Get one campaign's full record' and enumerates specific data included (untruncated offer URL, exact schedule, budgets/pacing, silent-conversions flag, payout goal type, targeting/payout rules), making the purpose highly specific. It also explicitly contrasts with list_campaigns, which renders a summary table, so it clearly distinguishes itself from its sibling.

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 explicitly states when to use this tool: 'use this when you need one campaign's complete data — e.g. before recreating it as a new campaign, or before editing it with update_campaign.' It also contrasts with list_campaigns, which is meant for scanning many campaigns, providing clear when-to-use and 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?

Despite annotations already declaring read-only/idempotent behavior, the description adds substantial behavioral context: conversion_type filtering zeroes impressions/clicks/media cost, paid_only defaults true to avoid inflated CR, ROI remains blank until cost is imported, and advertiser/publisher_email have role-based 403 limits. These are meaningful traits not visible in annotations or schema alone.

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 and dense, but every sentence contributes actionable nuance, from drill-down patterns to auth edge cases. It is front-loaded with the core purpose. Some details overlap with parameter schema descriptions (e.g., role limits for email params), which slightly reduces efficiency, but the overall structure is justified for a 15-parameter stats 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?

The description covers purpose, metrics returned, drill-down workflow, filter semantics, defaults, label handling, ROI behavior, and authorization limits. It is complete for an aggregation tool with no output schema, and it compensates for the absence of an output schema by clearly stating what the table contains. No significant gaps remain for an agent to invoke this tool 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 coverage is 100%, so the baseline is 3, but the description adds semantics beyond the schema: subN params always take raw keys while display uses tenant labels, conversion_type narrows to conversion rows rather than clicks, paid_only matches dashboard behavior and excludes informative pings, and email params can act as standalone filters versus group_by breakdowns. This materially improves an agent's understanding of parameter behavior.

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

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

The description opens with a specific verb+resource statement: 'Pull affset traffic stats grouped by a single dimension' and enumerates the exact metrics returned. This clearly differentiates it from sibling list/crud tools like list_conversions and list_campaigns, which return raw rows rather than aggregated stats.

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

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

The description gives a concrete drill-down workflow: 'first group_by=date or campaign_id, then narrow with filters... and change group_by' and explains role limitations (403 cases). It does not explicitly name alternative tools for row-level data or state when NOT to use this tool, but the workflow guidance is strong enough for an agent to choose and invoke it appropriately.

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 mark the tool as readOnly and idempotent, and the description adds behavior not inferable from the schema: both resources must be active, source-linked zones render the source's template, and the tenant's custom API domain is used. The explicit 'Read-only: builds the URL, changes nothing' reinforces rather than contradicts 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 with the core purpose and then adds prerequisite, derivation, source-template, domain, and safety details in a compact paragraph. Minor redundancy with the source_click_id parameter description keeps it from being a perfect 5, but every sentence still earns its place.

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

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

For a read-only URL builder with 9 parameters and no output schema, this description covers prerequisites, derivation behavior, source-template overrides, domain selection, and side-effect safety. An agent has enough information 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 coverage is 100%, and the schema itself documents each parameter well. The description adds useful context by connecting those parameters to the generated URL — 'with whatever sub values you want' — and by explaining how source-linked zones affect the resulting link.

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 concrete verb and resource ('Get the tracking link for an existing campaign + zone'), explains what kind of link it is ('/track/click ... no rotation or targeting checks'), and distinguishes it from the creation-time link generated by create_campaign. This makes it easy to separate from get_zone_url and other campaign 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 states when the tool is appropriate ('existing campaign + zone', after creation), and notes the same link is produced by create_campaign at creation, implying this is the re-derivation path. It also flags the prerequisite that campaign and zone must be active. It doesn't explicitly enumerate when not to use it versus get_zone_url, but the context is clear.

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

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

Although annotations already provide readOnlyHint/idempotentHint, the description adds substantial behavioral context beyond them: the URL rotates across active campaigns, captures tracking-template rendering vs. sub-convention prefill, mentions the optional cost macro, and explains custom API domain usage. The read-only statement aligns with annotations and adds a plain-language safety cue.

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 tightly written sentences, each earning its place: purpose and artifact, conditional behavior, and sibling differentiation. The most important routing information is placed last but still compact, with 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?

Despite having 8 optional parameters and no output schema, the description conveys what the tool returns (a URL), how it behaves under different zone states, and when to avoid it. All parameter defaults and behaviors are covered by the schema descriptions, and the sibling reference completes the contextual picture. Nothing critical is missing for an agent 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?

Schema description coverage is 100%, so the schema already documents every parameter in detail. The description adds contextual meaning by grouping source_click_id + sub1..sub5 and mentioning the cost macro, reinforcing the parameter conventions. It doesn't need to enumerate params because the schema does, but the description's reference to the sub convention adds a worthwhile layer.

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 the zone URL') and a concrete use case ('paste into a traffic source's campaign settings'), then precisely describes the artifact ('the /serve link that rotates across the zone's active campaigns'). It explicitly contrasts itself with get_tracking_link, so an agent can distinguish the two tools 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?

Gives clear context: when the zone is linked to a traffic source or not, and how the URL is built accordingly. Ends with an explicit alternative and the condition that selects it ('For a link straight to one active campaign without targeting checks, use get_tracking_link instead'), which fully routes the agent.

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

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

Annotations already cover readOnly, idempotent, and non-destructive. Description adds details about client-side name matching, lack of API search, pagination limits, and returned fields--useful context beyond what annotations provide.

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, no fluff, front-loaded with the core action. Every sentence adds value.

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

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

Covers scope, filtering, returned fields, and pagination. Missing mention of sorting/ordering parameters, but overall sufficient for a read-only list tool with rich annotations.

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

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

Schema coverage is 100%. Description clarifies the client-side nature of name_contains and contextualizes status and pagination parameters, adding meaning 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?

Clearly states it lists campaigns in the current namespace with filtering. Does not explicitly differentiate from sibling list tools (e.g., list_targeting_types), but the context implies uniqueness.

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?

Describes typical use (list campaigns with optional filters) but lacks explicit guidance on when to use alternatives or when not to use.

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 goes far beyond the readOnly, openWorld, idempotent, non-destructive annotations. It discloses that paid_only is server-side and not a simple payout filter, that several filters run client-side on the current page only, and that campaign_id/zone_id are not returned by the API. This is rich, non-obvious behavioral context.

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

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

The description is dense but every sentence carries unique value: purpose, returned fields, paid_only nuance, filter behavior, and API exclusions are all addressed. It is appropriately sized for a 10-parameter tool with subtle pagination and filtering behavior, and the critical semantics are 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?

There is no output schema, so the description must explain return values—it does by enumerating payout, spend, pixel type, click IDs, subs, postback outcome, and raw payload. It also covers edge cases like skip reasons and excluded API fields, making it complete for a complex read-only listing 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%, so the schema already documents each field, but the description adds critical semantics: which filters are server-side vs. client-side, what paid_only truly does with postback_skipped=non_goal_type, and that zero_payout needs payout visibility. This meaning is not inferable from parameter names alone.

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

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

The description immediately states a specific verb and resource: 'List recent conversion records (audit trail) for debugging payouts and pixel params.' It also enumerates the exact fields returned, which makes the tool's scope unmistakable. It distinguishes itself by describing the audit/payout context, which is unique among 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 clarifies the tool's intended use case ('for debugging payouts and pixel params') and even warns about paid_only semantics that could mislead users. It does not name alternatives, but no sibling tool appears to provide conversion records, so explicit exclusions were not necessary.

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 indicate readOnlyHint=true, idempotentHint=true, and safe behavior. The description adds valuable behavioral context: the distinction between global and per-zone rules, and how payout_goal_type affects conversion attribution.

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 two sentences long, no redundant words. It efficiently communicates key concepts without fluff.

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 list tool with one parameter and thorough annotations, the description fully explains behavior, output structure, and edge cases (payout_goal_type effect). No gaps remain.

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% for the single parameter (campaign_id). The description adds context about the output structure but does not significantly expand on parameter meaning 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 clearly states the tool lists a campaign's payout rules and payout_goal_type, explaining global vs per-zone rules. This specific verb+resource combination distinguishes it from sibling tools like list_targeting_rules or set_payout_rule.

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 provides clear context on when to use the tool (to list payout rules) and explains the structure of rules and the effect of payout_goal_type. While it doesn't explicitly exclude alternatives, the purpose is well-defined.

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 indicate read-only and idempotent. The description adds details about what data is returned (display names, raw keys for unlabeled) and the specific slots (sub1-sub5), providing useful behavioral context beyond 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?

Two concise sentences, front-loaded with action and resource, followed by usage context. No unnecessary words.

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

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

For a tool with no parameters and no output schema, the description fully covers what it does, what it returns, and how it is used. Complete and sufficient.

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

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

Input schema has zero parameters, so baseline is 4 per guidelines. Description adds no parameter info, which is acceptable as there are none.

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

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

The description clearly states the verb 'list' and the resource 'tenant's display names for sub1–sub5', specifies the scope (tenant-level) and behavior for unlabeled slots. It distinguishes from siblings like set_sub_labels and other list 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 usage context (used by get_stats, tracking-link, zone-URL) but does not explicitly state when to use or avoid this tool vs alternatives. However, the purpose is clear enough for a simple 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 readOnlyHint, idempotentHint, and destructiveHint, indicating safe read behavior. The description adds that rules gate serve rotation and the direct link does not enforce them, providing useful behavioral context beyond the annotations. It does not contradict 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 two sentences, no fluff. The first sentence explains the main function and output, the second adds an important behavioral note and a pointer to a sibling tool. Each sentence serves a purpose.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers the return fields, behavioral nuance, and provides a reference to a related tool. It does not mention pagination or whether all rules are returned at once, but for a list tool this is acceptable. Overall, it is sufficiently complete for an agent to use correctly.

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

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

The input schema has 100% coverage with a description for campaign_id. The description adds what the output includes (type, method, rule values), which is useful but not directly about the parameter. The parameter itself is sufficiently described 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 states it lists a campaign's targeting rules, specifies the type, method whitelist/blacklist, and rule values, and distinguishes from the sibling tool 'list_targeting_types' by directing the user to call that for type ids/names. The verb 'list' and resource 'targeting rules' are clear.

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

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

The description explains that rules gate '/serve rotation' and the direct tracking link does not enforce them, providing context on when the rules are relevant. It also advises to call 'list_targeting_types' for type details. However, it does not explicitly state when to use this tool versus alternatives like list_campaigns or list_payout_rules.

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 indicate read-only, idempotent, non-destructive behavior. The description adds value by noting that seeded types not evaluated by /serve are flagged, providing behavioral context beyond 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?

Two sentences, direct and front-loaded, with no extraneous information. Every sentence serves a purpose.

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

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

Given no parameters and no output schema, the description fully covers what the tool returns and provides actionable details (enforced types), making it complete for this simple listing 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?

With zero parameters, the description explains the output structure (id, name, description) and additional flagging, fully compensating for the absence of an output 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 clearly states the tool lists targeting rule types available in the tenant, including id, name, description, and flags types not evaluated by /serve. It distinguishes from siblings like list_targeting_rules by focusing on types rather than rules.

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 indicates using the id or name when setting campaign targeting rules and lists enforced types. While it lacks explicit when-not-to-use or alternatives, the context is sufficient for appropriate usage.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: it never returns API tokens and requires specific permissions. This goes beyond annotations to disclose behavioral traits.

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 efficient sentences: first communicates purpose and output, second clarifies exclusions and permissions. No unnecessary words; every sentence adds value.

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

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

Given the tool's simplicity, lack of output schema is compensated by listing returned fields. Annotations cover safety and idempotency. The description is sufficiently complete for an AI agent to understand and invoke 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 coverage is 100% with descriptions for both parameters (role filter and include_expired). The description does not add additional meaning to these parameters beyond what the schema provides. Baseline score 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?

Clearly states the tool lists team members with specific fields (email, role, manager, created/expiry) and explicitly distinguishes itself by noting it never returns API tokens. The verb 'list' and resource 'team members' are 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?

Specifies required role (owner/manager or scoped manager) for usage, providing clear context on who can invoke it. Does not explicitly mention when not to use it or direct to alternatives, but given no sibling tool serves the same purpose, this is adequate.

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, and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond annotations by disclosing that the stored network API token is write-only and only shown as set/none, and by explaining that the tracking template is what linked zones render in get_zone_url/get_tracking_link. This is valuable non-obvious 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?

The description is two dense sentences with no fluff. It front-loads the core purpose in the first clause and then packs only useful details: what is returned and the token visibility behavior. Every sentence 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?

There is no output schema, so the description appropriately explains the main return fields: tracking template, optional postback template, and token presence as set/none. With three optional parameters already fully documented in the schema, this is complete for a read-only listing tool. Minor gap: it does not explicitly mention pagination or filtering, but the schema covers those and the description's core job is fulfilled.

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 limit, offset, and status are already fully documented in the schema. The description does not add any additional parameter semantics, such as how pagination interacts with the status filter, but the baseline of 3 is appropriate because the schema carries the parameter documentation burden completely.

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: 'List the tenant's traffic sources'. It further clarifies the scope (tenant-level), the kind of entities (ad networks), and the key fields returned (tracking template, postback template, token status), which clearly distinguishes it from sibling tools like create_traffic_source and update_traffic_source.

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 clearly implies this is the read operation for traffic sources, and the read-only framing plus the mention of linked zone behavior gives context. It does not explicitly name alternatives like create_traffic_source/update_traffic_source or say 'use this when you need to view sources, not modify them', so there is no explicit exclusion, but the context is sufficiently clear.

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

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

Annotations establish that this is read-only, idempotent, and non-destructive. The description adds valuable behavior beyond annotations: client-side contains matching, the exact set of returned fields, and pagination defaults/max. This gives an agent a clear picture of what happens when the tool is invoked.

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 efficiently packed sentences with no filler. The action and scope are front-loaded, followed by the most important filtering and return information, then pagination. Every clause earns its place.

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

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

For a read-only list tool with no output schema, this description is complete: it lists the returned fields, the filter options, and pagination limits. Combined with the annotations, 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?

Schema description coverage is 100%, and each parameter already has a clear description. The tool description mostly restates status/name_contains and pagination behavior without adding new parameter-level meaning, so the schema carries the weight.

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 ('List traffic-source zones') plus the namespace scope, which clearly conveys what the tool does. It is distinct enough from sibling list_traffic_sources, though it does not explicitly differentiate itself from 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 implies usage for browsing and filtering zones by status/name with pagination. However, it does not provide explicit guidance about when to choose this tool over alternatives like get_zone_url, list_traffic_sources, or create_zone.

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

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

Beyond annotations (destructiveHint=true, readOnlyHint=false), the description adds that removal is a 'safe merge' preserving other rules, and reveals the dry-run default behavior. This provides useful context about non-destructive impact and preview capability.

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 exceptionally concise, using two short sentences to convey the core action, parameter identification methods, and default behavior. Every sentence adds value, with no wasted words.

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

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

For a tool with 5 parameters, no output schema, and simple operation, the description covers the essential logic (what it does, how to specify the target, and the dry-run/default mode). The missing output format is a minor gap but not critical for agent usage.

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%. The description adds value by explaining the alternative parameter groups (rule_id OR type+method) and the default behavior of confirm, going beyond individual parameter descriptions to clarify their interplay.

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

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

The description clearly states the verb 'remove', the resource 'targeting rule from a campaign', and adds context that it's a safe merge where other rules are kept, distinguishing it from siblings like set_targeting_rule and list_targeting_rules.

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 provides clear guidance on how to identify the rule (by rule_id or by type+method) and mentions the dry-run default with confirm=true to apply. It implicitly contrasts with set_targeting_rule but does not explicitly 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 indicate mutable (readOnlyHint=false) and potentially destructive (destructiveHint=true). The description adds significant context: dry-run by default, need confirm=true to apply, what 'run' does (enters rotation, counts against limit with specific error 402), and what 'pause' does (stops /serve and tracking links). This goes well beyond 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?

Three sentences: first states core purpose, second adds operational details and behavior, third provides explicit alternative. Every sentence is substantive with no fluff. Perfectly sized and structured for quick comprehension.

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 thoroughly covers when to use, behavior, and alternatives. However, since there is no output schema, the description could mention what the response looks like (e.g., status confirmation or updated campaign object). This minor gap prevents a perfect score.

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 descriptions in schema already explain each parameter. The description reinforces the action meanings but doesn't add new parameter-level details. Baseline 3 is appropriate since the schema already does the work.

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 specific verbs ('Run (activate) or pause') and identifies the resource ('campaign'), and explicitly distinguishes from sibling 'update_campaign' by saying 'For name/offer/budget edits use update_campaign.' This leaves no ambiguity about the tool's function.

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 clearly states when to use this tool (to run or pause a campaign), explains the default dry-run behavior and how to apply changes, and explicitly tells the agent when NOT to use it (for edits, use update_campaign). This is exemplary 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 indicate destructiveHint=true and readOnlyHint=false, but the description adds significant behavioral context: the exact matching behavior on conversion pixel type, zero-dollar recording for non-matching types, and the dry-run safety mechanism. This goes beyond 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?

Three sentences, each conveying essential information: purpose, behavior, and confirmation mechanism. No redundant words, front-loaded with primary action. Excellent structure.

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's complexity (3 params, no output schema), the description covers core behavior, matching logic, dry-run, and clearing. It lacks details on error states or permissions, but the annotations provide destructive hint and open-world hint, making this level of completeness adequate.

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% with clear parameter descriptions. The description reinforces key points (e.g., null/empty to clear) but does not add new semantic information beyond what the schema provides. 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 clearly states the verb 'set or clear' and the resource 'campaign's payout_goal_type', with specific behavioral details about when spend/payout apply. It distinguishes itself from sibling payout tools by focusing on goal-based conversion matching.

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 provides explicit usage guidance: use to set or clear a goal type, pass null/empty to clear, and dry-run default with confirm=true to apply. It does not explicitly contrast with alternatives, but the sibling list shows distinct tools, so context is sufficient.

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

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

The description discloses the upsert behavior (delete+create) and rollback on failure, which goes well beyond the destructiveHint annotation. It also mentions dry-run default, providing full behavioral context.

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

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

Three sentences, no wasted words. Front-loaded with the primary action, then provides key details on behavior and parameters. Every sentence 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 the tool's complexity (upsert, destructive, dry-run), the description covers essential behavioral aspects. It would benefit from mentioning the return value or success indicator, but it is mostly complete considering sibling tools provide listing/deletion.

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 baseline is 3. The description adds value by clarifying the semantics of zone_id (global vs override) and confirm (dry-run vs apply), which is not detailed in the schema descriptions.

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

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

The description clearly states the verb 'Set' and the resource 'campaign payout rule', and further distinguishes global vs per-zone, which differentiates it from sibling tools like list_payout_rules or delete_payout_rule.

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

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

It provides explicit instructions on when to use zone_id vs omit it for global rule, and explains the dry-run vs apply mode with confirm parameter. It does not contrast with alternatives like list_payout_rules, but the guidance is clear for correct usage.

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

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

Discloses side effects on 'stats column titles and link helpers', dry-run default, and destructive nature (matches destructiveHint=true). Adds value beyond annotations by specifying partial update and null clearing.

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 sentences, no wasted words. First sentence states core purpose, followed by key behaviors. Efficient and well-structured.

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

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

No output schema, but description explains dry-run mode and impacts. Covers mutation behavior, constraints, and required confirmation. Adequate for a 6-parameter tool with full schema coverage.

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 covers all 6 parameters at 100% with descriptions. Description adds 'max 40 chars each' (already in schema via maxLength) and 'partial update', but does not significantly enhance beyond 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?

Explicitly states 'Set or clear tenant display names for sub1–sub5', a specific verb-resource pair. Distinguishes from sibling list_sub_labels by implying mutation vs listing.

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?

Describes partial update behavior and dry-run vs apply. Implicitly separates from list_sub_labels. Could explicitly mention when to use this vs list_sub_labels but provides clear context.

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

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

The description adds value beyond annotations by detailing the upsert behavior (safe merge, rule matching by type+method), the dry-run default and confirm flag, the comma-separated rule format, and the normalization effect on delivery. This fully informs the agent about the tool's operations.

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 concise (three sentences), front-loaded with the core purpose, and each sentence adds essential detail without redundancy. No wasted words.

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 5 parameters, no output schema, and moderate complexity (upsert, dry-run, rule format), the description covers all necessary aspects: identification, merge behavior, rule format, confirm flag, and delivery implications. It is complete for an AI agent to use 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?

While the schema already has 100% parameter descriptions, the description adds extra context: rule format with examples (geo: BR,MX; unique_users: visits/hours), and that type can be looked up via list_targeting_types. This enhances understanding beyond the schema alone.

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

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

The description clearly states it upserts a targeting rule on a campaign, using a safe merge that preserves other rules. The verb 'Upsert' and resource 'targeting rule on a campaign' are specific and distinguish it from sibling tools like remove_targeting_rule and list_targeting_rules.

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 explains when to use the tool (to add or update a rule), how to identify the type via list_targeting_types, and mentions the dry-run behavior. It implicitly distinguishes from removal and listing tools, though it does not explicitly state 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?

Annotations already indicate destructiveHint=true, but description adds valuable context: dry-run default behavior, confirmation requirement, and the specific error condition (plan limit). No contradiction with 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?

Three concise sentences: first lists updatable fields, second explains dry-run/confirm, third provides alternative and warning. No wasted words.

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?

Covers key behaviors (dry-run, activation limit, separation from other tools) and field semantics. Lacks description of return value or error details, but no output schema is provided, making this acceptable.

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 description adds extra context for some parameters (e.g., 'rate: Internal advertiser rate (usually 0 for media-buying)' and 'status: active enters /serve rotation (plan limit)'), which helps the agent understand usage beyond basic schema types.

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?

Clearly states 'Update a campaign (partial)' and lists the specific fields it can modify. Distinguishes from sibling tools by naming set_campaign_status for run/pause and mentioning separate tools for targeting and payout rules.

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

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

Provides explicit guidance: DRY-RUN by default, pass confirm=true to apply, prefer set_campaign_status for run/pause, and warns about the active-campaign limit (402) when activating a paused 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 declare destructiveHint=true and readOnlyHint=false, but the description adds crucial nuance: 'DRY-RUN by default; pass confirm=true to apply' reveals the tool is non-destructive unless explicitly confirmed. It also discloses the propagation side effect ('Zones linked to the source pick the new tracking template up immediately') and the partial-update behavior, going well beyond the annotation 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 description is compact and front-loaded, starting with the operation and editable fields, then covering clearing semantics, propagation, and dry-run behavior in a few sentences. Every sentence adds a distinct behavioral fact with 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?

The description covers all call-affecting behaviors: partial updates, null clearing, zone propagation, and the dry-run/confirm default. With no output schema, an agent might not know what the dry-run returns, but the invocation path is well covered and the parameter schema fills in the remaining details.

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 cross-cutting semantics not visible in individual parameter descriptions, such as the partial-update rule ('only provided fields change') and the effect on linked zones. This additional meaning justifies a score above 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?

The description opens with 'Update a traffic source' and explicitly lists the editable fields (name, tracking_template, postback_template, api_token, status), making the verb and resource unambiguous. It clearly differentiates from sibling tools like create_traffic_source and update_zone by naming the resource type and the specific update action.

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 provides clear context on how to use the tool: partial updates ('only provided fields change'), how to clear fields ('pass null (or "") to clear'), and the dry-run/confirm gate. It does not explicitly name alternatives or state when not to use it, but the usage context is strong enough for an agent to select it correctly.

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 mark this as non-read-only and destructive, so the description's added dry-run behavior ('DRY-RUN by default; pass confirm=true to apply') is highly valuable and clarifies the safety model. It also discloses side effects ('Linking a traffic source makes get_zone_url/get_tracking_link render its tracking template') and partial update behavior beyond what annotations convey.

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

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

Four sentences with no fluff. The most important facts—what is updated, partial update semantics, null-clearing, and the dry-run default—are front-loaded and each sentence earns its place.

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

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

For an 8-parameter mutation with no output schema and destructive annotations, the description covers the critical operational needs: partial update, null semantics, dry-run confirmation, and the downstream effect on tracking template rendering. It is complete enough for an agent to call the tool 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: 'only provided fields change' clarifies partial update, and the linking side effect ties traffic_source_id to the get_zone_url/get_tracking_link behavior.

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

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

The description states a specific verb ('Update') and a specific resource ('a traffic-source zone'), then enumerates the exact fields affected. This clearly distinguishes it from update_traffic_source and create_zone, so an agent can select it 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?

The description gives useful operational context—partial update semantics, null-to-clear, and dry-run/confirm—but does not explicitly state when to choose this tool over alternatives such as update_traffic_source or set_campaign_status. Sibling tools are available, but no when-not-to-use 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false. The description adds: conditional data (company info only if /api/tenant read succeeds), that binding is fixed at startup, and reassures 'Read-only, no side effects'. No contradictions.

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 somewhat lengthy but front-loaded and every sentence adds value. Could be slightly more concise, but it efficiently packs all necessary 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 zero parameters and no output schema, the description is remarkably complete: it lists all return fields, notes conditional availability, provides usage rationale, and gives an anti-pattern to avoid. No gaps remain.

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?

No parameters exist, so the description focuses entirely on output semantics, which are fully detailed: namespace, API base, dashboard URL, plus optional fields. This adds significant value beyond the empty input 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 clearly states the tool returns tenant information including namespace, API base URL, dashboard URL, and optionally company name/timezone/custom domain. The verb 'return' and resource 'tenant' are specific. It distinguishes itself from sibling tools like list_campaigns or get_stats which operate on different resources.

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 advises calling 'once at the start of a session' and contrasts with 'guessing the namespace from the owner's email'. Mentions one MCP instance = one tenant. No sibling alternative is needed as no other tool serves this purpose.

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