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

Annotations only declare the generic safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the description carries real added value: it discloses that existing participants are returned unchanged, that enrollment bypasses affiliate review, and that a new participant may be silently created with affiliateStatus: APPROVED. It does not mention auth/permission requirements or rate limits, keeping it out of the top tier.

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

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

The definition is a dense but front-loaded paragraph that leads with the core add-or-fetch behavior and then layers the conditional enrollment rules in a logical order. Sentences are long and information-packed rather than padded, with no filler, though the final conditional sentence is somewhat convoluted.

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 documented, and the description handles the campaignId default and enrollment branching well. Still, for a 12-parameter mutation tool at 25% schema coverage, several parameters (referralStatus, fingerprint, mobileInstanceId) and any permission/scope requirements remain undocumented, leaving gaps an agent may hit.

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

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

Schema description coverage is only 25% across 12 parameters, and the description compensates well for the hardest ones (isAffiliate, referredBy, campaignId fallback to GROWSURF_CAMPAIGN_ID, email as the lookup key). But it leaves metadata, firstName, lastName, ipAddress, fingerprint, mobileInstanceId, and the referralStatus enum entirely unexplained, so it only partially fills the coverage gap.

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

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

The description opens with a specific verb+resource and a lookup key: 'Add or fetch a participant by email,' and immediately clarifies upsert semantics ('Existing participants are returned unchanged'), which behaviorally distinguishes it from growsurf_get_participant and growsurf_update_participant. It stops short of naming a sibling or stating the read-only alternative, so it falls just below the top tier.

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 routing context for the tricky cases: 'trusted direct enrollment and bypasses the public application review flow for affiliates,' plus conditional rules for isAffiliate and referredBy. However, it never says when to prefer this tool over growsurf_get_participant (pure read) or growsurf_update_participant (modify existing), leaving the main sibling-selection decision to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts: the output is Markdown prompts/acceptance checks and nothing is created or executed, which a name like 'eval' would otherwise imply. It stops short of describing depth/format of the generated checks, but that is partly covered by the 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?

Two sentences, zero filler: the deliverable and scope come first, the non-goal and sibling routing second. Every clause carries information an agent needs for selection.

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

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

Output schema exists, so return-value detail is not required, and annotations cover the read-only/idempotent nature. The only meaningful hole is parameter meaning, which the description does not address; otherwise it is complete for a two-parameter generation 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 0% for two parameters, and the description mentions neither programType nor includeOneShotPrompts. The enum values (referral/affiliate/both) and the boolean's name are partly self-explanatory, but there is no explanation of how programType narrows the generated checks or what 'one-shot prompts' produce, so the description fails to compensate for the coverage gap.

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

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

States a specific verb and artifact ('Generate Markdown prompts and acceptance checks') plus the exact evaluation scope (starter content, rewards, configuration, frontend installation). It also names two siblings and what they are for, so an agent can separate it from growsurf_program_design_advisor and growsurf_integration_guide 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?

Explicitly routes the agent: use program_design_advisor to pick a design, or integration_guide to plan web integration. It also states a negative boundary in plain terms ('Does not create a program or run the checks'), which prevents mistaking it for growsurf_create_program_resource.

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 the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description usefully adds that it returns code without executing API calls, clarifying this is pure generation, but offers nothing on output shape or limits.

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

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

Front-loaded with purpose, then selection parameters, coverage, the no-execution constraint, and finally sibling routing. Four sentences with no padding; each adds distinct 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The only real gap is the four context parameters (email, campaignId, referredBy, participantIdOrEmail) that an agent gets no guidance on anywhere.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains `language`, `workflow`, their `all` defaults, and what the workflow values cover, but leaves `email`, `campaignId`, `referredBy`, and `participantIdOrEmail` entirely undocumented in both schema and description.

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 (Generate) plus resource (Markdown code examples for official backend REST API libraries) with the target languages enumerated. It clearly separates itself from snippet-producing siblings by naming backend REST libraries versus browser/native SDKs.

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 routing conditions: use `growsurf_client_snippets` for browser JavaScript and `growsurf_mobile_sdk_guide` for native/React Native setup. It also states the tool returns code without executing API calls, so there is no ambiguity about side effects.

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?

Excellent transparency beyond annotations: explicitly states deletion is permanent and irreversible, lists cascading effects (referrals, rewards, commissions, payout records removed), explains status codes, and clarifies the 202 analyticsErasure behavior and that repeating rows won't finish erasure. Adds significant actionable context not captured in 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 and critical destructive warning, then efficiently covers chunking, return values, and edge cases. Slightly dense with detail but 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 the 2-parameter schema with full coverage, output schema existence, and the tool's destructive nature, the description covers everything needed: immutability warning, cascading effects, chunking guidance, status semantics, and analytics erasure nuances. No critical gaps.

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

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

Schema description coverage is 100%, so parameter documentation is already thorough. The description adds clarification that mixed lists are allowed and re-iterates the 200-entry limit, but does not provide additional semantic depth 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 (delete) and resource (participants) with explicit scope (bulk, one request, from your GrowSurf program). Clearly distinguished from siblings like list_participants or update_participant.

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 chunking for lists over 200 entries and mentions campaignId defaulting behavior, but does not explicitly state when to use this tool versus alternatives (e.g., single participant deletion via update_participant). Usage context is implied rather than guided.

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, so the safety profile is covered. The description adds the meaningful effect (a pending trigger is removed, and only before the delay elapses), but says nothing about permissions, what happens if no trigger is pending, or error behaviour.

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

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

Two tight sentences, front-loaded with the action and its timing constraint. The trailing 'Returns { success, message }' is largely redundant given an output schema exists, which keeps it out of 5 territory.

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 and rich annotations, the missing pieces are narrower: the participant-identifier choice and the no-pending-trigger / error case. For a destructive mutation tool, that leaves an agent guessing on inputs even though the effect and safety profile are covered.

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

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

Schema coverage is only 33% and the description does not compensate: it never explains the participantId/participantEmail anyOf, which is the key input decision. The campaignId fallback it restates is already worded in the schema itself, so it adds no new meaning.

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

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

States a specific verb+resource: cancelling a pending delayed referral trigger, with the timing constraint ('before the delay elapses'). The 'delayed referral trigger' framing distinguishes it from the sibling growsurf_trigger_referral, which creates rather than cancels triggers.

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 one motivating scenario ('e.g. on refund/cancellation'), which implies when to reach for it, but names no alternatives, prerequisites, or when-not conditions. An agent still has to infer the boundary between this and growsurf_refund_transaction or growsurf_trigger_referral.

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

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

With annotations covering the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description still adds real value: short-lived URLs with an UTC expiresAt, screenshots reflect the saved program at capture time, and installation on the customer's site is not verified. The note that 'a failed inline image alone does not establish that the URL expired' is an unusually useful failure-mode disclosure.

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 sentences but each carries distinct information: purpose, return shape, capture semantics, non-verification caveat, failure-mode caveat, boundary exclusions, and targeting rule. It is front-loaded and free of filler, though slightly denser than needed for a one-parameter 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?

Even though an output schema exists (so return values need not be explained), the description still characterizes the returned URLs and their expiry, plus capture semantics and failure modes. An agent has everything required to decide when to call it and how to interpret the result.

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

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

Schema description coverage is 100% for the single campaignId parameter, so the baseline is 3. The description's 'Targets campaignId if supplied, otherwise GROWSURF_CAMPAIGN_ID' merely restates the schema default, though it is worth noting the schema marks campaignId required while both sources describe an omitted-parameter default.

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

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

The description gives a specific verb+resource ('Capture temporary GrowSurf preview screenshots') and states the precondition ('after a draft program is saved'). No sibling tool produces screenshots, and the scoping to the referrer Window and referred-friend experience makes the output concrete.

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 clearly states the triggering context ('after a draft program is saved') and draws explicit negative boundaries ('does not accept arbitrary URLs, HTML, JavaScript, or external screenshot targets'). It does not name an alternative sibling, but no sibling performs this function, so the routing gap 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds real value by negating side effects ("Does not install code or change a program") and by disclosing the output form (Markdown) and that placement guidance is included. It does not describe pagination or output length, but this is a generator tool where that matters little.

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, both front-loaded: the capability first, then the explicit sibling routing. No filler, no repetition of the title, and every clause carries selection-relevant 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?

An output schema exists, so return values need no explanation, and the description covers what the tool produces, what it deliberately does not do, and how it differs from its neighbors. The one gap is that the 8 optional configuration parameters are left entirely to the schema.

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

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

Schema description coverage is 0% across 8 parameters, so the description is the only place parameter meaning could be conveyed, and it says nothing about programType, singlePageApp, referralTrigger, or the various include* toggles. Two enums are self-explanatory and the boolean names are semi-descriptive, which keeps this above a 1, but the description does no compensating work for the coverage gap.

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

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

States a specific verb and resource (generate Markdown browser JavaScript and CSS examples) and enumerates the covered domains: referral tracking, embeddable elements, and the GrowSurf Window. It also names the three sibling snippet tools it is not, so an agent can distinguish it 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?

Explicit routing: use growsurf_embeddable_element_snippet for a single HTML element, growsurf_grsf_config_snippet for window.grsfConfig, and growsurf_api_library_snippets for backend REST code. Each alternative is paired with the condition that selects it, leaving nothing 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds genuinely non-derivable behavior: what is copied (active rewards) versus what is not (integrations, credentials), plus the fact that the output is a DRAFT. It stops short of noting that repeated calls create duplicates (non-idempotency) or any permission requirements.

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

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

Three short sentences, result state front-loaded, then the copy semantics, then the parameter resolution rule. No hedging or filler; 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?

An output schema exists, so return values need not be described, and the description covers the operation's key semantics and the single parameter's resolution. Minor gaps remain around error/conflict behavior and explicit sibling routing, but nothing needed to invoke it correctly is absent.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents campaignId, its fallback to GROWSURF_CAMPAIGN_ID, and the ID-reuse behavior. The description restates the fallback rather than adding syntax or format detail, 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?

Specific verb (clone) plus resource (GrowSurf program/campaign) and a concrete outcome: a new DRAFT program. It also disambiguates GrowSurf's 'program = campaign' terminology, which matters given both growsurf_create_campaign and growsurf_clone_campaign exist as 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?

Usage is implied: clone duplicates an existing campaign's configuration rather than building a new one from scratch, which contrasts with growsurf_create_campaign. However no sibling is named and no explicit when-to-use/when-not-to-use condition is stated.

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

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

Beyond annotations, it discloses extensive behavioral traits: the key is returned once and cannot be recovered, is locked behind email verification with a specific 403 error, unverified accounts are deleted after 7 days, the owner's first dashboard sign-in replaces the key causing `NOT_AUTHORIZED_ERROR`, and the trial details. This is a high level of disclosure for a destructive, open-world creation 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?

The description is long but dense with useful operational details and front-loads the core action and key prerequisite. A few sentences (e.g., participant email verification) are tangential to the tool's immediate invocation, but most content 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 complexity, high-risk nature (destructiveHint=true), and an output schema that exists, the description is nearly complete on return and behavioral aspects. The main gap is the lack of parameter semantics for three of four fields, which the schema also fails to document.

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

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

Schema description coverage is 0%, so the description must carry the burden for the four parameters. It only indirectly implies that the `email` parameter is the owner's email and that personal/disposable addresses are rejected; it says nothing about `company`, `firstName`, or `lastName`, leaving their purpose and format undocumented.

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

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

The description states a precise verb and resource: 'Create a brand-new GrowSurf account and return an API key.' It also uniquely distinguishes itself from siblings by noting it is the only tool that does not require `GROWSURF_API_KEY`, which is crucial routing information for an agent.

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

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

It provides explicit when-to-use guidance including prerequisites (owner approval, ToS/Privacy acceptance) and names the hosted OAuth connector as an alternative that retains credentials. It also clarifies that this is the only no-API-key tool, leaving little ambiguity about when to select 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?

Beyond annotations, the description discloses that the program starts in DRAFT status, is owned by the credential's bound team, currencyISO defaults to USD and is immutable after creation, goal is set only at creation, and omitting rewards seeds switched-off starter rewards that award nothing. It also states that editor-tab configuration is not accepted and that the response includes the new program id, all of which materially inform 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 purpose and then proceeds through creation defaults, immutability rules, and edge cases in a mostly linear order. It is longer than a minimal description but each sentence adds useful behavioral context; minor redundancy exists around goal and rewards, 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?

With an output schema present, the description need not explain return values, and it still notes the response includes the new program id for convenience. Annotations cover the safety profile, and the description adds substantial creation behavior, defaults, and constraints, though it does not address permissions/plan requirements or clarify all seven parameters. It is complete enough for correct invocation in most 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 description coverage is low at 29%, so the description must compensate, and it does so for key parameters: type is the only required field, currencyISO defaults to USD and is immutable, rewards are optional and affect starter rewards, and goal sets sharing settings only at creation. It leaves name, companyName, and companyLogoImageUrl without explicit semantic guidance, but their purpose is largely self-evident from the parameter names.

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 new GrowSurf program (campaign) with type-appropriate starter content and optional inline rewards.' It clearly differentiates from update/clone siblings by emphasizing that it creates a new program, starts it in DRAFT, and only requires type. An agent can identify the core action and scope 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?

It gives clear context for when to include rewards, when to omit them, and how goal affects creation, plus a boundary that 'Editor-tab configuration is not accepted here' and that the call 'Does not require GROWSURF_CAMPAIGN_ID.' However, it never names an alternative sibling tool (e.g., clone_campaign or update_campaign) for closely related tasks, so it falls short of explicit when-to-use-vs-alternative 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 already declare the safety profile (not read-only, not idempotent, not destructive), lowering the bar. The description adds a genuine behavioral constraint the annotations don't carry: type/program compatibility (AFFILIATE-only for affiliate programs) and the campaignId defaulting rule. It stops short of auth requirements or failure modes, but this is solid added 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, purpose first, then the type-compatibility rule, then the targeting rule. Nothing is redundant, though the constraint sentence is somewhat dense for the space it gets.

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 output schema exists so return values needn't be explained, and the program-type rule is the single most important piece of context for this tool. But for a 23-parameter mutation tool with nested objects, the description is far from complete — it omits required pairings, the meaning of the many optional fields, and error behavior.

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

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

With 23 parameters at only 22% schema description coverage, the description must carry the semantic load and does not. It explains only `type` and `campaignId`, leaving 21 parameters (including the nested value/referredValue/commissionStructure objects) undocumented in prose, so an agent gets little beyond the raw 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 (create) plus resource (campaign reward / reward config) and names the parent program scope. It is trivially distinguishable from siblings like update_campaign_reward, delete_campaign_reward, and list_campaign_rewards.

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 real routing context: `type` must match the program type, and campaignId falls back to GROWSURF_CAMPAIGN_ID. However it never names the sibling tools an agent might confuse it with (update/delete/clone reward), so the when-not guidance is only 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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds genuinely non-obvious behavior: secret is write-only, is never returned, and is used to produce the GrowSurf-Signature HMAC header on deliveries. It does not disclose rate limits or repeated-call 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?

Five information-dense sentences, purpose front-loaded, each clause carrying real semantics (write-only secret, signature header, env-var fallback). Slight redundancy in restating that payloadUrl is required, which the schema already marks.

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, and annotations carry the safety profile. The description covers the mutation semantics an agent needs, with the only real gap being the isEnabled flag and any note on how to verify the webhook afterward.

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 only 40% schema description coverage, the prose compensates well for four of five parameters (payloadUrl required, events omitted means no subscriptions, secret write-only signing semantics, campaignId defaulting to the env var). isEnabled is left entirely undocumented in both schema and description, so it is not fully covered.

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 ('Add a webhook to your GrowSurf program'), which cleanly separates it from the update/delete/test webhook siblings by verb alone. It does not name any sibling explicitly, so it falls short of 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?

Usage is implied rather than stated: the campaignId fallback to GROWSURF_CAMPAIGN_ID and the 'omit events to subscribe to no events' note give context for calling it, but there is no explicit when-to-use guidance or steering toward growsurf_update_campaign_webhook / delete siblings.

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

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

With annotations already declaring readOnlyHint=false, idempotentHint=false and destructiveHint=false, the description still adds meaningful behavior: it creates *or* fetches a participant, performs trusted direct enrollment that skips review, and resolves the target campaign from `GROWSURF_CAMPAIGN_ID` when not passed. It omits token lifetime/scope, what happens on repeat calls, and any auth/permission requirements for the mutation side.

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 core action front-loaded before the trust/flow caveat and the campaign-resolution detail. Minor filler ('via GrowSurf REST') could be cut, but nothing is bloated or buried.

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

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

An output schema exists, so return values needn't be explained, and the description does cover the dual create-or-fetch nature and trusted-enrollment semantics. For a 12-parameter, nested-object tool it still leaves too much unaddressed: no permissions/auth needs, no note on what fetching an existing participant means for the other parameters, and no token characteristics.

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

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

Schema description coverage is only 25% across 12 parameters, so the description carries the compensation burden and largely fails to meet it. Its only parameter-relevant statements ('targets campaignId', 'trusted direct enrollment' for isAffiliate) restate what the schema's own `campaignId` and `isAffiliate` descriptions already say, leaving metadata, referralStatus, mobileInstanceId, ipAddress, fingerprint and the rest undocumented in both places.

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 compound operation: create/fetch a participant, then mint a participant-scoped mobile SDK token 'via GrowSurf REST'. That is far more specific than the title alone and distinguishes it from plain participant tools. It stops short of explicitly contrasting itself with the closest sibling, growsurf_participant_auth_hash, so an agent still has to infer which token mechanism applies.

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 real usage condition — participant creation here is 'trusted direct enrollment' that 'bypasses the public application review flow' — which tells the agent this is not the path for public applicants. However, it never names an alternative tool or states when to prefer growsurf_add_participant, growsurf_participant_auth_hash, or the public application flow; the routing is only implied.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), yet the description adds real value beyond them: resources default to draft unless isPublished is set, files are capped at 10 MB, and the uploadTicket is one-time with an unmodified uploadResult. Auth requirements and rate limits are unaddressed, keeping this below 5.

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

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

Front-loads the type distinctions before the flow/default details, then closes with the reference link and campaign targeting. It is a dense single paragraph with no redundancy, though the API reference URL and the closing targeting sentence are slightly less essential than the type constraints.

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 no explanation, and annotations cover the safety profile. The description supplies the type-specific constraints and default-publish behavior, but omits the prerequisite step of obtaining the upload ticket, which an agent calling the FILE branch would need.

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

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

Schema coverage is 50% over 10 params; the schema already documents url, text, uploadTicket, uploadResult, and campaignId with essentially the same wording the description repeats. The description does add the isPublished default semantics, but leaves title, category, and description unexplained, and its "campaignId if supplied, otherwise GROWSURF_CAMPAIGN_ID" claim sits awkwardly against a schema where campaignId is required.

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 ("Create") and resource ("a FILE, LINK, or TEXT resource for participants") and immediately distinguishes the three variants. An agent can tell this apart from growsurf_update_program_resource or growsurf_list_program_resources 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 clear per-type conditions (LINK requires an HTTPS url, TEXT requires text, FILE requires uploadTicket + uploadResult) and states the draft-vs-published behavior. It never names the sibling alternatives it interacts with, notably growsurf_prepare_program_resource_file for the FILE flow, so the routing guidance is implicit rather than 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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds genuinely useful extra context: the reward is deactivated, dropped from the reward set, and connected upfront-discount coupons are cascaded-cleaned. That cascade is a non-obvious side effect 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?

Three tight sentences, front-loaded with the action and its side effects, then parameter and return notes. Nothing is wasted or buried.

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

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

For a destructive mutation with an output schema already covering the { id, success } return and annotations covering the safety profile, the description supplies the missing pieces: cascading cleanup behavior and the campaign target resolution rule.

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?

campaignRewardId has no schema description, and the text compensates by identifying it as the reward key. campaignId's fallback to GROWSURF_CAMPAIGN_ID is repeated from the schema, and the phrasing 'if you pass it' implies optionality while the schema marks it required, a minor ambiguity.

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 (delete) and resource (campaign reward / reward config) plus the program scope. An agent can distinguish it from siblings like growsurf_update_campaign_reward and growsurf_delete_campaign_webhook 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?

The description never explicitly says when to delete vs. update or deactivate a reward, nor when not to use it. Usage is implied by the verb and the campaignId targeting note, which is enough to function but leaves the alternatives 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds the response shape ({ id, success }) and the environment-variable fallback for targeting, which goes beyond the annotations, though it omits irreversibility/confirmation guidance.

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, no filler: action and scope first, then return value, then targeting rule. Every sentence carries information an agent needs.

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

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

An output schema exists and annotations cover the destructive/idempotent semantics, so the description is nearly sufficient for a two-parameter delete. The one gap is that it does not reconcile its 'otherwise GROWSURF_CAMPAIGN_ID' defaulting language with the schema's requirement that campaignId be passed.

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

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

Schema coverage is 50% (campaignId documented, webhookId bare), so the baseline is 3. The description adds the GROWSURF_CAMPAIGN_ID fallback for campaignId, but it also implies campaignId is optional while the schema marks it required, which muddies rather than clarifies the parameter contract.

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

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

States a specific verb and resource ('Remove a webhook from your GrowSurf program') and scopes it by id, which clearly separates it from list_campaign_webhooks, create_campaign_webhook, update_campaign_webhook, and test_campaign_webhook. An agent can pick this tool 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?

It explains which program the call targets (explicit campaignId vs GROWSURF_CAMPAIGN_ID fallback), which is useful context, but it never states when to use this tool versus its webhook siblings or any prerequisite such as resolving a webhook id first. Usage is implied by the name rather than guided.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by specifying that the reusable Media Center asset survives the delete, which is exactly the kind of collateral-damage clarification a destructive tool needs, though it omits auth requirements and reversibility.

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

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

Two sentences, zero filler, with the primary action front-loaded and the two clarifications (asset preservation, target resolution) following in priority order. Nothing is redundant with the title or schema.

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

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

An output schema exists, so return values need not be explained, and the annotations carry destructiveness/idempotency. For a two-parameter destructive call the description covers the essential risk caveat and target resolution; only auth/permission expectations and the undocumented resourceId remain thin.

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

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

Schema coverage is 50% – campaignId is fully documented in the schema (including the GROWSURF_CAMPAIGN_ID default and the note about new programs), while resourceId has no description at all. The description partially compensates by explaining campaignId targeting and by characterizing resourceId as a participant resource, but it gives no format, ID source, or lookup hint.

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

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

States a specific verb and resource ("Delete a participant resource from your GrowSurf program") and clarifies scope by noting the reusable Media Center asset is not removed, which disambiguates it from asset-level deletion. Siblings like create_program_resource / update_program_resource / list_program_resources are never named, so routing relies on the reader inferring the CRUD pattern.

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

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

Usage is implied by the verb "delete" and the resource it targets, but there is no explicit when-to-use vs when-not, no named alternative, and no prerequisites (permissions, confirmations). The only actionable guidance is the campaignId resolution rule, which is targeting mechanics rather than usage policy.

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

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

Annotations only give generic flags (destructive, openWorld, non-idempotent); the description adds real operational context: auto-injected compliance footer, suppression of unsubscribed participants, the team-verification / verified-domain prerequisite, and that HTTP 400 is returned until verification exists. It also discloses the async nature ("accepted for delivery"), which the annotations do not.

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

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

Front-loaded with the core action, then progressively adds constraints and prerequisites. It is dense and long, but nearly every sentence carries actionable constraint information; the inline enumeration of email types is verbose yet genuinely useful.

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

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

An output schema exists, so return values need not be restated, and the description still explains the delivery semantics and 400-failure condition. Gaps are minor: it never warns that retries may produce duplicate sends (consistent with idempotentHint=false), nor how participantId vs participantEmail resolve when both are passed.

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 57%, and the description meaningfully compensates: `emailType` must be the camelCase key, valid values are enumerated per program type, `body` must include `{{emailFooter}}` under INLINE layout mode, and `campaignId` defaults to `GROWSURF_CAMPAIGN_ID`. It does not clarify precedence if both participantId and participantEmail are supplied.

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

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

Starts with a specific verb+resource: "Send an email to a participant (by GrowSurf participant ID or email)." This clearly distinguishes it from config-oriented siblings like get_campaign_emails and update_campaign_emails, which manage templates rather than send mail.

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 the two mutually exclusive modes ("Provide EITHER `emailType` ... OR `subject` + `body`") and enumerates when each applies. It also lists which template types cannot be sent and the `welcomeNonReferred` eligibility rule, so an agent knows the boundaries before invoking.

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 carry readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context that it produces code and does not install anything or mutate a program, reinforcing the non-destructive nature beyond the annotation defaults.

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, front-loaded with the core action, then the constraint, then the sibling routing. No filler, and each sentence adds a distinct decision-relevant fact.

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 code-generation tool with an output schema, the description covers purpose, scope limits, and alternatives adequately. The remaining gap is that the nested participant/auth parameter details are left entirely to a schema that has no per-field descriptions.

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

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

Schema description coverage is 0%, so the description must compensate. It signals the two meaningful inputs ('Choose `element`' and 'optionally include participant authentication attributes'), which maps to the enum and the withAuthAttributes/participant params, but it does not document the enum options, the required email inside the nested participant object, or the default of withAuthAttributes.

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 one embeddable element's HTML as Markdown') and explicitly distinguishes itself from two named siblings. An agent can identify the tool's role 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?

It names the alternatives and the conditions that select them ('growsurf_client_snippets for a broader browser integration or growsurf_grsf_config_snippet for page-level participant auto authentication') and clarifies the negative case ('Does not install the element or change a program').

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 closed-world, so safety is covered. The description adds genuine value beyond that: the warning that embedded reward settings do not imply a reward was earned/approved/delivered, and that earned-reward records belong to the participant — a real semantic caveat that prevents misreading the response.

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, front-loaded with the core fetch action and targeting rule, followed by the reward caveat. The caveat is slightly tangential to a get-details call but is compact and defensible; nothing is padded.

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

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

An output schema exists, so return values need not be described, and the reward-semantics caveat covers the main interpretive risk. Combined with annotations, the description is sufficient for correct invocation, though a note on relation to list_campaigns would make it airtight.

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 100% schema description coverage and a single parameter, the schema already explains campaignId, its default, and its behavior for newly created programs. The description's restatement of the same campaignId/GROWSURF_CAMPAIGN_ID fallback adds nothing beyond the schema, 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?

Specific verb ('fetch') plus resource ('campaign/program details') makes the operation clear, and clarifying that 'campaign' equals 'program' helps terminology mapping. It does not, however, explicitly differentiate from the sibling growsurf_list_campaigns, so an agent must infer the single-vs-many distinction.

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 how to target a campaign but never states when to use this tool versus alternatives like growsurf_list_campaigns, growsurf_get_campaign_design, or growsurf_update_campaign. No when-not conditions or prerequisites are given.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive behavior: the fixed stage order, advocate vs affiliate cohort grouping fields, the per-participant observation window, and a critical caveat that zero/null may reflect unavailable history rather than no action.

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?

Dense but well ordered: purpose first, then grouping semantics, stage list, defaults, interpretation caveat, and targeting last. Every sentence carries operational weight, though the enum-heavy middle sentence is a little packed.

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 explanation is unnecessary, and the description covers the remaining gaps an agent needs: cohort defaults, stage ordering, observation window, and how to read null/zero results.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema does not: what happens when both cohort bounds are omitted, which field cohorts group on per program type, and the campaignId/GROWSURF_CAMPAIGN_ID fallback.

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 ('Fetch strict activation ... in one enrollment cohort') and scopes it tightly enough to separate it from the broader get_campaign_analytics and get_participant_analytics siblings. It never names an alternative tool explicitly, so it stops short of full sibling differentiation.

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 usage guidance: omit both cohort bounds for the latest fully matured cohort, each participant gets the chosen 7- or 30-day window, and read coverageStartAt/state/reason before interpreting nulls. It lacks explicit when-to-use-this-instead-of-X routing against sibling analytics 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, so the safety profile is covered. The description adds real behavioral context the annotations cannot: engagement coverageStartAt/state/reason distinguish measured zeroes from partial or unavailable history, and it discloses defaults and limits (days default 365, max 1825, timezone/platform scoped to engagement only).

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

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

A dense but well-ordered paragraph: scope first, then interval, then include values, then timeframe constraints, then targeting. Nearly every sentence carries information, though the date/timestamp constraint is restated in both the prose and the schema, adding a little redundancy.

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

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

With an output schema present the description need not explain return values, and it still covers defaults, limits, enum usage, engagement-only parameters, and campaignId fallback to GROWSURF_CAMPAIGN_ID. Nothing an agent needs to invoke this 8-parameter 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?

Schema description coverage is high (88%), so the baseline is 3, but the description adds cross-parameter semantics the schema does not: timezone and platform apply only to engagement, engagement requires include=engagement, and the startDate/endDate pairing constraints (both positive ms timestamps, endDate >= startDate, 1825-day span) are spelled out as a coherent rule set.

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 ('Fetch analytics for your GrowSurf program') and enumerates the metric families returned (participants, referrals, impressions, shares, affiliate revenue/commission/payout). An agent can tell it is a program-level analytics read, though it never names the closest sibling (growsurf_get_campaign_activation_analytics) or explains how the two differ.

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 teaches *how* to drive the tool (interval for a series, comma-separated include values, days vs. explicit dates, campaignId fallback) but never states when this tool should be chosen over activation analytics or participant analytics. Usage context is implied rather than explicit, so the agent must infer the routing decision.

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/closed-world, but the description adds real behavioral detail: unknown or missing `participantAvatarStyle` resolves to `INITIALS`, the confirmation section is omitted when no confirmation fields are stored, stored `null` is returned as `null` while omitted values use localized defaults, and `trafficInsights` defaults differ by program type. These fallback/omission semantics are useful, though they describe the payload rather than the call itself.

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?

Purpose is front-loaded in the first clause, but the body is a single run-on sentence of roughly 180 words enumerating every returned design field group — content an existing output schema already carries. With an output schema present, this enumeration is largely redundant padding that buries the few genuinely useful sentences about defaults and omission.

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

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

For a single-parameter read tool with rich annotations and an output schema, the definition covers purpose, targeting, and fallback semantics adequately; return values need not be explained given the output schema. The remaining gap is the absence of any routing guidance relative to the many sibling read 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?

There is a single parameter with 100% schema description coverage, so the schema already documents `campaignId`. The description's 'Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID' essentially restates the schema rather than adding format, constraint, or resolution detail beyond it.

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: 'Fetch the configured design fields for your GrowSurf program', then enumerates the design areas involved (window content, colors, sharing, avatars, widget, traffic insights, login, payout confirmation). It does not, however, differentiate itself from the closest read siblings such as growsurf_get_campaign, growsurf_get_campaign_options, or growsurf_get_campaign_installation, so an agent must infer the boundary from naming alone.

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

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

The description is entirely about what is returned and how defaults resolve; it never states when to call this versus alternatives (e.g., use get_campaign for general settings, update_campaign_design to change design). There is no exclusion or prerequisite guidance, leaving the agent to infer that this is the read counterpart of growsurf_update_campaign_design.

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 the safety profile is covered. The description adds genuinely useful behavioral context beyond that: sender.fromEmail is read-only and only changeable in the dashboard after domain verification, sender fields may be null before configuration, and fromName/replyToEmail cannot be nulled out. Some of this is oriented toward the update flow rather than describing this read call's own 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-loaded with the core purpose in the first clause, followed by compact technical details. Four sentences mostly earn their place, though the update-oriented caveats sit oddly in a getter's description and slightly dilute the focus.

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 and annotations cover the read-only/idempotent profile, so return-value and safety disclosure are not needed here. The description supplies the extra semantics an agent needs (null handling, read-only fields, target defaulting), leaving only minor gaps around when to prefer this tool over its siblings.

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

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

With a single parameter at 100% schema description coverage, the schema already documents campaignId, its minLength, and the GROWSURF_CAMPAIGN_ID default. The description restates the same targeting/default behavior without adding format or edge-case detail, so the baseline of 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 ("Fetch the Emails tab configuration for your GrowSurf program") and enumerates what is included (participant/admin templates, settings, read-only fields), which distinguishes it from siblings like growsurf_get_campaign_design or growsurf_get_campaign_options. It never explicitly names the update sibling, so the get-vs-update boundary is only implied.

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 spends its guidance on update semantics ("When updating, omit unchanged sender fields") rather than stating when an agent should call this read tool versus alternatives. The campaignId fallback to GROWSURF_CAMPAIGN_ID is stated, but there is no explicit trigger condition or exclusion relative to growsurf_get_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 readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds genuine value beyond that: it discloses the return payload is the complete object with every field's current value and that it round-trips with the update call, plus the campaign-ID fallback. Minor gaps only (no note on whether a missing program errors).

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 compact sentences, front-loaded with the resource, then the return contract, then the targeting rule. No filler, though the parenthetical scope gloss and trailing default could be trimmed 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?

With an output schema present the description doesn't need to enumerate return fields, yet the round-trip note is useful orientation. Combined with the annotation-covered safety profile and the fully specified parameter, an agent has enough to call this correctly; only the error/edge behavior for an unresolvable program is unmentioned.

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 parameter is fully documented in the schema, including the GROWSURF_CAMPAIGN_ID default, so the description's restatement adds little. Baseline 3 applies when the schema carries the parameter semantics.

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 (Fetch) and a specific resource (the Installation tab configuration: embed/installation and tracking setup) scoped to a GrowSurf program. This clearly separates it from sibling readers like get_campaign_design, get_campaign_emails, and get_campaign_options without needing to open 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 the target-selection rule ('Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID') and implicitly positions the tool as the read counterpart to update_campaign_installation via 'the same shape you send back on update'. It lacks an explicit statement of when to prefer it over adjacent readers, so it stops short of a 5.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real value beyond them: it promises the full object with every field and current value, states it round-trips with the update call, and pre-empts a likely misinterpretation of autoFulfillRewards:false. It does not cover auth/permission needs or rate limits.

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

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

Front-loaded with the purpose, then the return shape, then the caveat and the targeting rule. Every clause carries information an agent needs; the parenthetical enumeration is dense but earns its space by naming the configurable sub-areas.

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 need not describe return values, yet it helpfully states the shape is write-back compatible. Target selection and default are covered. Only minor gaps remain (auth requirements, whether a program must already exist), and none would block a correct call.

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 campaignId parameter is fully documented in the schema, including the GROWSURF_CAMPAIGN_ID default. The description restates the same targeting rule ('Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID') without adding syntax or format detail, so the baseline of 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?

Specific verb ('Fetch') plus specific resource ('Options tab configuration for your GrowSurf program'), and it enumerates the sub-areas the Options tab covers (triggers, anti-fraud, affiliate enrollment, notifications, languages). This distinguishes it clearly from siblings like growsurf_get_campaign and growsurf_update_campaign_options.

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

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

Usage is implied rather than stated: 'the same shape you send back on update' anchors it as the read-side partner of growsurf_update_campaign_options, and the autoFulfillRewards note warns against a wrong inference. But there is no explicit when-to-use/when-not guidance or named alternative for cases where a different getter is appropriate.

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 safety, yet the description adds substantial behavioral detail: the dashboard-completion requirement, the connected/enabled/autoDisabled result fields, the programVerified=false fallback that still returns a production link, and program-type applicability rules. This is rich context beyond structured data.

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

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

Dense prose that front-loads the purpose and the API-cannot-connect caveat. Every sentence carries useful information, though the program-type and result-field details are somewhat packed together rather than scannable.

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 read tool this is fully covered: connection semantics, edge cases (programVerified false), result flags, and program-type caveats are all addressed, and an output schema exists so return structure need not be re-explained.

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 100% schema coverage the baseline is 3, but the description adds genuine meaning beyond the schema: camelCase key examples, the program-type restrictions (Tango Card, Tremendous, Bask Health referral-only; Wise affiliate-only), and the campaignId fallback behavior. It does not add syntax or validation 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?

States a specific verb and resource: return a dashboard link to an integration's connect panel in the GrowSurf Program Editor. It also clarifies the critical constraint that the API cannot connect accounts itself, distinguishing this tool from connect/action tools and from growsurf_list_integrations.

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 for use: the user must complete the dashboard flow, so this tool is the hand-off point. However, it does not explicitly name sibling alternatives (e.g. growsurf_list_integrations or growsurf_integration_guide) or 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 cover readOnly/idempotent/non-destructive, so the bar is lower, and the description adds genuine value beyond them: the campaignId fallback to GROWSURF_CAMPAIGN_ID, and non-obvious field interpretation ('zero referralCount is consistent with CREDIT_AWARDED', fulfillment flags are not delivery confirmation). It still omits auth/permission requirements.

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

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

Purpose and lookup keys are front-loaded, and the dense backtick-heavy clauses about referralStatus, referralCount, and rewards each carry distinct semantic meaning. It is compact for the amount of interpretation it conveys, though the field-semantics run-on could be trimmed.

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 explain return values, yet it goes further and disambiguates the trickiest output fields. Purpose, lookup keys, and campaign targeting are all covered; only permissions and rate/auth context are absent.

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

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

Schema coverage is only 33%, so participantId and participantEmail have no schema descriptions. The description partially compensates by establishing that either identifier is accepted and that campaignId falls back to an env default, but adds no format hints for the email/ID and does not restate the anyOf alternation beyond 'ID or email'.

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 ('Fetch a single participant') plus the two lookup keys, which implicitly separates it from list_participants. It never names a sibling explicitly, so the differentiation is inferred 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 establishes lookup context ('by participant ID or email address') and targeting rules, but never says when to reach for this tool versus list_participants or get_participant_analytics, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds useful behavioral context: sort order (most recent first), pagination mechanics, and that the response offset is the next-page cursor (null at end). However, it doesn't cover auth requirements or rate limits.

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

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

Three compact sentences, appropriately front-loaded with the core action and lookup keys, then pagination details, then campaign targeting. Every sentence carries useful information, though the pagination and targeting could be marginally tighter.

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 paginated read tool with an output schema and full annotation coverage, the description suffices: it explains ordering, pagination cursor semantics, lookup keys, and campaign targeting defaults. It needn't detail return values since an output schema exists.

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

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

Schema description coverage is only 20% (only campaignId is documented), so the description must compensate. It does: it explains limit range (1-100, default 20), offset semantics (skips logs), and the campaignId fallback to GROWSURF_CAMPAIGN_ID. It adds real meaning beyond the bare 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?

States a specific verb+resource: 'List a participant's activity logs' with the lookup key (participant ID or email) and ordering. This clearly distinguishes it from siblings like growsurf_get_participant or growsurf_get_participant_analytics, which return different data about the same entity.

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 through the ID-or-email lookup and campaign targeting, but it never states when to use this tool versus gets like get_participant or get_participant_analytics. It provides context but no explicit exclusions or alternatives.

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

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

Annotations already declare a safe read (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial behavior: what the base response contains, what `activation` unlocks, the 1825-day cap, and the crucial null-milestone interpretation rule. It also warns that date params do not filter the base response or milestones.

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 purpose and then layers optional behavior; nearly every sentence carries non-obvious rules. It is dense and slightly long, but no sentence is pure 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?

Despite 8 parameters and conditional (anyOf/allOf) schema constraints, the description covers the base vs optional response split, include semantics, date-window rules, and the null-milestone caveat. With an output schema present, no return-format explanation is needed, so nothing material 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 75%, so the schema already documents most parameters. The description still adds integration-level meaning: that date params do not filter the base response, that `endDate` must be >= `startDate` within 1825 days, and the campaignId targeting fallback to GROWSURF_CAMPAIGN_ID.

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

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

States a specific verb (Fetch) and resource (analytics for one participant) plus the two identification keys (participant ID or email). The 'one participant' scoping cleanly distinguishes it from the campaign-level siblings like get_campaign_analytics and get_campaign_activation_analytics.

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 conditional guidance: add `activation` for eligibility/milestones, request both `activation` and `series` for covered buckets, and how to bound ranges with `days` or `startDate`/`endDate`. It lacks explicit routing against adjacent siblings (get_participant, get_participant_activity_logs), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds genuine behavioral context beyond that: per-provider status fields, the meaning of `activeProvider` (the provider that currently gets paid, or null until the participant confirms one), and the appearance of a repair reason when a delivery bounced or a recipient was invalidated. That is real semantics the annotations cannot convey.

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

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

The description is front-loaded with the core capability and the provider enumeration, then moves to return semantics, then the campaignId fallback, in a sensible order. It is somewhat dense with em-dashes and backticked field names, but every clause carries information an agent needs.

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

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

An output schema exists, so the description need not enumerate return values, yet it still summarizes the important ones (status, confirmed email, recipient type, repair reason, activeProvider), which is helpful for selecting the tool. Combined with the identifier and campaignId fallback notes, the definition covers what an agent needs to invoke it correctly; a minor gap is the absence of guidance on combining participantId and participantEmail.

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

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

Schema description coverage is only 33% — participantId and participantEmail have no schema descriptions at all. The description compensates by explaining that lookup is 'by GrowSurf participant ID or email' and that campaignId is optional and falls back to GROWSURF_CAMPAIGN_ID, which clarifies the anyOf/required structure the schema encodes only mechanically. It does not, however, add format examples or say what happens if both identifiers are supplied.

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

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

The description names a specific verb and resource ('Get a participant's payout-destination status') and scopes it across every enabled payout provider (PayPal and/or Wise), which clearly separates it from the write-side sibling growsurf_request_participant_payout_destination_confirmation. It also enumerates the fields returned, so an agent knows exactly what question this tool answers.

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

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

Usage is implied — you call it to inspect payout-destination state — and the description does tell the agent it can look up by either participant ID or email, which is a routing hint. However, it never explicitly says when to use this versus the sibling confirmation-request tool, nor when the lookup is not appropriate. Implied rather than stated 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 already declare readOnlyHint/idempotentHint/destructiveHint, so safety is covered. The description adds value beyond annotations by specifying what is not returned (personal profiles, internal identifiers) and clarifying the meaning of verificationStatus, which is useful 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, all informative, with the main purpose front-loaded in the first sentence. No filler or redundancy; each sentence contributes a distinct piece of information (what it fetches, verification meaning, and non-returned data).

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

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

With zero parameters, an output schema, and full annotation coverage, the description rounds out the picture by explaining verification semantics and data exclusions. No essential information is missing for a read-only fetch 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?

The tool has zero parameters, so there is no parameter semantics to explain. The description's note about environment variables (API key vs campaign ID) adds relevant configuration context beyond the empty 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 and resource: "Fetch the team bound to the API key or OAuth connection." This clearly identifies the tool's function and distinguishes it from sibling tools like get_campaign or list_campaigns, even without naming an 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 useful context by explaining that verificationStatus must be VERIFIED before a program can email participants, implying when this tool is relevant. It also states the credential requirements (requires API key, not campaign ID), which helps route usage, though it does not explicitly name alternative tools or exclusions.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so safety is covered. The description adds that the output is generated HTML placed in <head>, which is useful context, but says nothing about why certain flags exist, what the generated code does at runtime, or any auth/rate constraints.

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

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

Two tight sentences, no filler, with the core purpose front-loaded and the placement constraint appended where it is most useful.

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

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

An output schema exists, so return values need no explanation, and the annotations cover the safety profile. However, for a 7-parameter code generator the description leaves all parameters and most behavioral nuance undocumented, making it only partially complete.

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

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

Schema description coverage is 0% across 7 parameters, so the schema documents nothing. The description only alludes to window.grsfConfig and never explains hash, email, campaignId, affiliateJoin, useCampaignIdPlaceholder, enableParticipantAutoAuth, or includeAutoAuthCommentHeader, leaving the agent to guess at all 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 (Generate) plus resource (HTML code for Participant Auto Authentication) and even names the mechanism (window.grsfConfig). It distinguishes itself from generic snippet siblings by specifying the auto-auth use case, though it does not explicitly name the closest alternatives like growsurf_client_snippets.

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 placement hint ('belongs in <head>, before the GrowSurf Universal Code') clarifies how the output is consumed but not when to select this tool over the other snippet tools. Usage is only implied through the auto-auth context; there are no explicit when/when-not rules or named alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety burden is largely carried. The description adds the meaningful clarification that this is a planning/advisory tool producing Markdown rather than performing inspection or mutation, which sharpens the agent's mental model beyond the flags.

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 with zero filler; purpose and output are front-loaded, the negative scope comes second, and the sibling routing closes it out. Nothing repeats.

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?

Safety is covered by annotations and return shape by the output schema, so those needn't be in prose. The remaining gap is the five parameters, four of which are undocumented in both schema and description — adequate overall but not fully complete for a tool with this many inputs.

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

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

Schema description coverage is only 20% (just webhookSecurity), and the description says nothing about the five inputs — programType, singlePageApp, referralTrigger, participantAuthEnabled are left entirely to bare enum names and defaults. The description does not compensate for the coverage gap, so an agent gets little help interpreting or selecting these 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?

States a specific verb and resource ('Plan a web integration for a referral or affiliate program') and goes on to name the concrete outputs (Markdown steps for Universal Code, participant identification, referral/sale tracking, webhook verification). It also explicitly scopes what the tool is not ('Does not inspect or change a program'), letting an agent separate it from the many mutating 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?

Explicitly routes the agent to alternatives by condition: `growsurf_client_snippets` for browser JavaScript, `growsurf_api_library_snippets` for backend code, `growsurf_mobile_sdk_guide` for native/React Native. This is exactly the when-to-use-a-sibling guidance most definitions omit.

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. Description adds valuable semantics beyond that: deleted rewards excluded, switched-off/ungrouped included, and the subtle point that config presence does not mean a reward was earned. This is meaningful context for interpreting results.

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

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

Front-loads scope, then qualifications about inclusion/exclusion and the config-vs-earned distinction. A bit dense with semicolons but every clause adds signal.

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

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

Output schema exists, so return values needn't be described. The description covers scoping, defaults, exclusions, and the important semantic caveat about earned vs configured rewards. Nothing an agent needs 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 baseline is 3 arguable. The description adds the fallback behavior (GROWSURF_CAMPAIGN_ID when campaignId not supplied), which reinforces the schema and clarifies precedence ordering for the single param.

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

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

States a specific verb (List) and resource (Campaign Rewards) with precise scope: includes switched-off rewards and rewards whose group is not selected, excludes deleted ones. Distinguishable from gets/updates and from participant earned-reward records.

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 frames what the tool returns and clarifies the crucial distinction that earned reward records belong to the participant, implying this tool is for configuration listing. It doesn't explicitly name sibling alternatives like get_participant, but the boundary is clear from context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavior: deleted programs are filtered out, IDs are included, and no campaign ID binding is needed. It says nothing about ordering, pagination, or result size limits.

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

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

Three short sentences, front-loaded with what is returned and immediately followed by the two facts an agent needs (deleted items excluded, no campaign ID required). 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-shape explanation is unnecessary, and the annotations carry the safety profile. For a zero-parameter list tool the description supplies everything needed to select and 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?

The tool takes zero parameters, which is the baseline-4 case, and the description correctly signals that no GROWSURF_CAMPAIGN_ID binding is required. There is nothing further for it to add.

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 ('List the GrowSurf programs') plus the scope ('available to the bound team'), which cleanly separates it from the singular growsurf_get_campaign and the reward/resource list siblings. It does not explicitly name a sibling, and it uses 'programs' while the tool name and the rest of the toolset use 'campaigns', a terminology mismatch an agent must bridge.

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?

'including their IDs for program selection' and 'Does not require GROWSURF_CAMPAIGN_ID' both describe when this tool is the right entry point (discovering a campaign ID before calling the many campaign-scoped tools). No explicit exclusions or named alternatives are given, so it stops short of a 5.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds a genuinely useful behavioral detail beyond that: secrets are never returned, which tells the agent the output is sanitized. It stops short of noting pagination or result limits.

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

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

Two short sentences, front-loaded with the action and scope, with no filler. The second sentence duplicates what the schema already says about campaignId fallback, so it is slightly redundant, but the cost is small.

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

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

With an output schema present, the description needn't explain return values, and annotations carry the safety profile. Combined with the secret-redaction note and targeting rule, an agent has what it needs to call this correctly; only pagination/result-size behavior is left implicit.

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 campaignId parameter is fully documented in the schema, including the GROWSURF_CAMPAIGN_ID fallback. The description's 'Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID' largely restates that schema text rather than adding new meaning, 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 (List) and resource (webhooks) scoped to a GrowSurf program, which cleanly separates it from the create/update/delete/test webhook siblings. The parenthetical about secrets not being returned further sharpens what the tool actually returns.

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

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

Usage is implied by the verb and the sibling set — an agent can infer this is the read path versus growsurf_create_campaign_webhook or growsurf_delete_campaign_webhook — but the description never says when to prefer it or names any alternative. The only explicit conditional is about which campaign is targeted, not about when to call the 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 cover the read-only/idempotent/non-destructive profile, yet the description goes further: it defines each returned field's meaning, including the notable autoDisabled failure behavior, explains omission semantics for inapplicable integrations, and clarifies that connection is dashboard-only. This is genuinely additive 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?

Front-loads purpose and integration names, then layers field semantics, omission rules, API limitation, and targeting. Every sentence carries information, though the field-by-field enumeration partly overlaps the existing output schema, adding slight redundancy.

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

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

With an output schema present, return-value documentation is not required, and annotations cover the safety profile. The description fills the remaining gaps: what the fields mean, what gets omitted, and how the campaignId is resolved — leaving nothing an agent needs 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% for the single campaignId parameter, so the schema already carries the semantics. The description restates the targeting rule (campaignId if supplied, otherwise GROWSURF_CAMPAIGN_ID) without adding new syntax or format detail beyond what the schema provides, 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 ('List the integrations available to your GrowSurf program') and enumerates the concrete integration set (Stripe, PayPal, Wise, Mailchimp, Slack, Zapier, Webhooks). It is clearly distinguishable from siblings like growsurf_integration_guide and growsurf_get_integration_connect_link.

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 strong context on what the tool can and cannot do, noting that account connection happens in the dashboard and is not available through the API, and that inapplicable integrations are omitted. It stops short of explicitly naming an alternative sibling (e.g. get_integration_connect_link) for connection flows, so routing is implied rather than spelled out.

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

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

Annotations already declare read-only/idempotent safety, and the description adds real behavioral context: newest-page-first ordering, that filtered results are ordered by participant ID, the paging handshake via nextId, and results carrying participant IDs. That is meaningful beyond the safety flags, though it omits rate limits or result-size expectations.

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