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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses real behavior: existing participants are returned unchanged, the call bypasses the public application review flow, and the enrollment status outcome depends on isAffiliate/referredBy. These are consequential side-effect details the annotations cannot express.

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 and the key 'existing participants returned unchanged' behavior, then the affiliate logic. The conditional rules are non-obvious and earn their space, though the description is dense and could be tightened.

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

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

With an output schema present, return values need not be explained, and annotations cover the safety profile. The description thoroughly covers the affiliate/referral enrollment logic and targeting default, but omits auth/permission needs and most secondary parameter meaning for an 11-param mutation tool.

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

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

Schema coverage is only 18%, so the description must carry the load, and it does add genuine meaning for the trickiest params (isAffiliate outcomes, referredBy interaction, campaignId default). But it leaves the majority of the 11 params (fingerprint, ipAddress, mobileInstanceId, referralStatus, metadata, name fields) undocumented, so it only partially compensates.

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: 'Add or fetch a participant by email.' The add-or-fetch semantics is distinctive and distinguishes it functionally from get_participant (fetch only) and update_participant, though no sibling is named explicitly, keeping it from a 5.

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

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

Provides clear context of use — 'trusted direct enrollment and bypasses the public application review flow for affiliates' — and conditions for the affiliate/referral flags. However it never names an alternative tool or states when not to use this one versus get_participant/update_participant, so it stops short of explicit routing.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, so the description only needs to add extra behavioral context. It does so by specifying that the tool produces 'one-shot' evaluation prompts and acceptance checks, and by listing the four focus areas, which goes beyond mere annotation repetition.

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 entire description is one front-loaded sentence with no filler. It states the verb, resource, purpose, and key scope areas in a compact list, so every part 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?

Output schema and annotations cover return values and safety behavior, and both parameters are optional with defaults, so an agent can invoke the tool minimally. However, with no schema descriptions for parameters, the description leaves programType semantics and the effect of includeOneShotPrompts unexplained, creating a notable completeness gap.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining the two parameters, but it does not mention programType or define what includeOneShotPrompts controls. Only the word 'one-shot' weakly hints at one parameter, and 'program-creation' weakly hints at the other; this is insufficient compensation for a low-coverage 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 action, 'Generate one-shot GrowSurf program-creation eval prompts and acceptance checks', naming both the deliverable and its purpose. The colon-delimited list of coverage areas further distinguishes it from the many operational sibling tools, making its unique role clear.

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

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

The phrase 'for agent steering' implies the intended context, and the content areas suggest evaluation scenarios. However, there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives, leaving the selection logic mostly to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no behavioral detail beyond generating snippets, but it does not contradict the annotations either.

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 one concise, front-loaded sentence with no filler. It communicates the deliverable and scope quickly, though a short structured format could improve scannability.

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

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

With six optional parameters, multiple workflow and language enums, and many sibling snippet tools, more contextual guidance is needed for reliable invocation. The description omits when to use this tool, how to populate workflow-specific identifiers, and how it relates to client/embeddable snippet alternatives; the output schema helps with return values but not invocation context.

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 needed to explain how to use email, language, workflow, campaignId, referredBy, and participantIdOrEmail. It only echoes the language options and mentions the mobile participant token workflow, leaving most parameters unexplained; the schema itself already provides the enums and defaults.

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

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

The description states a specific action and resource: generating official REST API library snippets for five named languages, and explicitly calls out the Create Mobile Participant Token workflow. It is reasonably distinguishable from sibling snippet tools like client snippets and embeddable snippets, though it does not name those alternatives.

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

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

There is no guidance about when to use this tool versus sibling tools such as growsurf_client_snippets, growsurf_embeddable_element_snippet, or growsurf_grsf_config_snippet. The description also does not explain which workflow or language option fits a given scenario.

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

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

Annotations already flag destructiveHint and idempotentHint, but the description adds substantial context beyond them: deletion removes referrals, rewards, commissions, and payout records; 200 and 202 both can carry NOT_FOUND or ERROR rows; 202 signals pending analyticsErasure; repeating successful rows does not complete erasure. This is exactly the behavioral depth 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?

Front-loaded with the destructive warning, then entry format, limits, and response semantics in a logical order. It is dense rather than wasteful, but the run of response-code detail (200/202, DELETED/NOT_FOUND/DUPLICATE/ERROR, analyticsErasure) is long enough that a tighter phrasing would still convey the same guidance.

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

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

For a destructive bulk mutation with two parameters, the description covers safety, input limits, chunking, target resolution, and partial-failure semantics (per-row statuses, summary counts, 202 erasure state). Nothing an agent needs to invoke it safely and interpret mixed outcomes is missing.

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

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

Schema coverage is 100%, so the schema itself documents mixed ID/email lists and the 1-200 bound. The description still adds value by clarifying the chunking strategy for lists over 200 and restating how campaignId falls back to the environment variable, which helps an agent plan multi-call deletions.

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 ('Bulk delete participants from your GrowSurf program') plus scope (single request, up to 200 entries) and target (campaignId or GROWSURF_CAMPAIGN_ID). An agent can distinguish it from growsurf_list_participants, growsurf_add_participant, and growsurf_update_participant without opening any schema.

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

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

Gives clear operational context: bulk deletion in one request, chunking larger lists across multiple calls, and how the target campaign is resolved. It does not explicitly name the sibling tools or state when deletion is inappropriate versus softer alternatives (e.g. update), so it stops short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=false, so the safety profile is covered. The description adds what is destroyed (a pending delayed trigger) and the target-resolution fallback, but omits auth requirements, failure modes, and what happens if the delay has already elapsed.

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

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

Three short sentences, front-loaded with the operation and then the return shape and targeting rule. No filler; 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?

With an output schema present, return values need not be described, and annotations carry the safety profile. The description is nearly complete for a low-complexity, low-parameter tool; the main residual gap is the participant identifier choice 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?

Schema coverage is only 33%: only campaignId is documented in the schema. The description clarifies campaignId targeting ('Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID') but says nothing about the participantId vs participantEmail either-or requirement encoded in the anyOf, leaving that gap to the schema alone.

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

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

The description gives a specific verb+resource+scope: 'Cancel a pending delayed referral trigger for a participant before the delay elapses.' An agent can tell this undoes a pending trigger versus siblings like growsurf_trigger_referral or growsurf_refund_transaction. It stops short of explicitly naming and contrasting a sibling.

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

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

It supplies a clear triggering context — 'before the delay elapses (e.g. on refund/cancellation)' — which tells the agent when this tool is the right call. There are no explicit exclusions or named alternatives, so it falls 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 only declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false); the description goes well beyond them by disclosing that URLs are short-lived, that an `expiresAt` UTC timestamp is returned, that screenshots reflect the saved program at capture time rather than live installation state, and that a failed inline image does not prove URL expiry. That is exactly the kind of operational caveat an agent needs before 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?

Purpose and return contract are front-loaded in the first two sentences, with constraints following. Every sentence carries a distinct constraint, though the negative-acceptance list and the expiry caveat could be tightened 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?

For a single-parameter, zero-required tool with an output schema and full annotation coverage, the description supplies the remaining gaps an agent needs: lifetime of returned URLs, capture-time semantics, and the distinction between a broken image and an expired URL. 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 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`' restates the schema's default-resolution behavior without adding format or syntax 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 ('Capture temporary GrowSurf preview screenshots') and scopes it precisely to 'after a draft program is saved'. No sibling tool covers screenshot capture, so the agent can route to it unambiguously from the name and first sentence 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?

Gives a clear precondition ('after a draft program is saved') and explicit negative boundaries ('does not accept arbitrary URLs, HTML, JavaScript, or external screenshot targets'), which tells the agent when not to reach for it. It never names an alternative tool for adjacent needs, so it falls 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 provide readOnlyHint=true and idempotentHint=true, making it clear this is a safe read-only operation that can be called repeatedly without side effects. The description adds that it generates snippets and provides placement guidance, but does not disclose the format of the output (e.g., exact code blocks, language specifics) beyond JS + CSS. With annotations covering safety, the description adds moderate value, but it could state that no programmatic changes are made and the output is purely for the UI.

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

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

The description is a single sentence that is concise and front-loaded with the core purpose ('Generate copy-pasteable client-side snippets'). It covers key topics (referral tracking, embeddable elements, GrowSurf Window) and adds placement guidance without excessive detail. It could be more structured, but it is efficient and 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?

The tool has 8 parameters with 0% schema description coverage and no parameter documentation in the description, which is a major gap. There is an output schema, which may define the snippet structure, but since it is not shown here, it is unclear. The description is not complete enough for an agent to correctly set all options without further guidance. It needs to either describe parameters or link to resource guides.

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%, meaning none of the 8 parameters are described in the schema. The description does not explain any parameters, such as programType, singlePageApp, referralTrigger, or includeGrowSurfWindow. This is a significant gap because an agent must guess the meaning of each boolean and enum from names and defaults, which is error-prone. The description should at least summarize key options to compensate for the lack of schema descriptions.

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

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

The description clearly states the tool generates client-side snippets for GrowSurf referral tracking, embeddable elements, and the GrowSurf Window, specifying JS + CSS and placement guidance. It distinguishes from sibling tools like growsurf_api_library_snippets and growsurf_embeddable_element_snippet by focusing on client-side copy-pasteable snippets for app UI work. The title 'Client Snippets' is more generic, but the description clarifies the specific output.

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 mentions placement guidance for app UI work, indicating it is intended for front-end integration. It implicitly differentiates from API snippets by naming 'copy-pasteable client-side snippets', but it does not explicitly state when to use this tool versus siblings like growsurf_api_library_snippets or growsurf_mobile_sdk_guide. It lacks explicit when-not-to-use alternatives, but the context is clear enough for an agent to infer the primary use case.

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

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

Annotations only declare readOnly=false, destructive=false, idempotent=false. The description adds genuinely useful behavior the annotations cannot convey: integrations and credentials are NOT copied while active rewards ARE, and the output is a DRAFT rather than a live program. It stops short of noting that repeated calls produce multiple drafts (relevant to idempotentHint=false) 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, front-loaded with the core action and result state, with the copy semantics placed before the id-targeting detail. Slightly redundant with the schema on the campaignId default, but no wasted framing.

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 description covers the two things an agent most needs for a mutating clone: what state the result is in (DRAFT) and what is/isn't carried over. The one notable omission is the non-idempotent consequence of calling it more than once.

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

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

Schema coverage is 100% for the single parameter, and the schema description already documents the GROWSURF_CAMPAIGN_ID fallback. The description's targeting sentence therefore restates schema content rather than adding format, validation, or constraint detail. Baseline 3 applies.

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

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

The description names a specific verb and resource ('Clone your GrowSurf program (campaign)') and specifies the resulting state ('new DRAFT program'), which is more than a restatement of the title. It does not explicitly contrast itself with the nearby growsurf_create_campaign sibling, so the agent must infer that cloning differs from creating from scratch.

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

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

Usage is only implied: you clone an existing program when you want a duplicate draft. There is no statement of when to prefer this over growsurf_create_campaign, no prerequisites, and no exclusions. The targeting sentence describes which id is used, not when the tool 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?

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 readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the write/non-idempotent profile is known. The description adds the type-compatibility constraint and the campaign-targeting default, but says nothing about idempotency, error behavior, or side effects beyond that, so it adds only modest value over the annotations.

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

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

Two tight sentences with the core action and the critical constraint front-loaded; no filler. Slightly dense with backticked identifiers but still readable and well-ordered.

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 two most consequential rules (type compatibility, targeting default) are covered. However, for a 23-parameter creation tool at 22% schema coverage, the description leaves the majority of the parameter surface unexplained.

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 22% across 23 parameters, so the description must compensate, and it does so only for `type` (compatibility rules) and `campaignId` (defaulting). Many parameters (limit, order, title, isVisible, couponCode, numberOfWinners, conversionsRequired, etc.) remain undocumented in both places, leaving a substantial 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 ('Create a new campaign reward (reward config)') and scopes it to the GrowSurf program, which cleanly separates it from the list/update/delete campaign_reward siblings. It does not explicitly name an alternative, but the create action is unambiguous.

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

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

Gives real preconditions: `type` must match the program type (affiliate vs referral programs), and the target is `campaignId` if passed, otherwise GROWSURF_CAMPAIGN_ID. This tells the agent when the call is valid and how targeting resolves, though it does not discuss when to prefer a different 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 safety profile (readOnlyHint=false, openWorldHint=true, non-idempotent). The description adds genuine value beyond them: the secret is write-only and used for HMAC signing via the GrowSurf-Signature header, and omitting events subscribes the webhook to no events. It omits error/retry or rate-limit behavior, so not a full 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?

Four compact sentences that are front-loaded with purpose, followed by parameter-specific notes. No filler, though the parameter sentences are dense and a slightly more scannable structure would help.

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. The description covers the required parameter, the non-obvious write-only secret, and the campaign targeting default. The only material gap is the unexplained isEnabled flag.

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 description compensates well: it clarifies payloadUrl is required, explains events semantics including the omit case, expands on secret's write-only signing role, and documents campaignId's fallback to GROWSURF_CAMPAIGN_ID. Only isEnabled is left unexplained, keeping it from a 5.

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: 'Add a webhook to your GrowSurf program.' An agent can readily distinguish this from the sibling list/update/delete/test webhook tools based on the verb 'Add'. It stops short of explicitly naming those alternatives, but the action is unambiguous.

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

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

Provides operational guidance (payloadUrl required, omitting events subscribes to nothing, targeting campaignId vs GROWSURF_CAMPAIGN_ID default), which implies when and how to call it. However, it never routes between this and sibling tools like update_campaign_webhook or test_campaign_webhook, nor states prerequisites or exclusions.

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

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

Annotations already establish the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds genuinely useful context: participant creation bypasses the public application review flow for affiliates, and the campaign target falls back to an env var. It stops short of disclosing auth requirements, rate limits, or what 'create or fetch' means for repeat calls.

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, front-loaded sentences with no filler. The core action comes first and the enrollment/targeting caveats follow, which is appropriate sizing for the information present.

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 enrollment semantics are covered. However, for an 11-parameter mutation tool with 18% schema coverage, the description should have compensated for the many undocumented fields; instead it leaves that gap open.

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 ~18% — just campaignId and isAffiliate are described. The description adds only the campaignId fallback behavior, leaving 9 of 11 parameters (email, firstName, lastName, metadata, ipAddress, referredBy, fingerprint, referralStatus, mobileInstanceId) 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?

The description names a specific verb+resource (create a participant-scoped mobile SDK token) and clarifies the two-step behavior (create-or-fetch participant, then tokenize). It is clearly specific, but it never differentiates this tool from close siblings like growsurf_add_participant or growsurf_mobile_sdk_guide.

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 through the 'trusted direct enrollment' framing and the campaignId/`GROWSURF_CAMPAIGN_ID` targeting note, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative for the non-mobile participant case.

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=false, idempotent=false, destructive=false, openWorld=true. The description adds genuinely new behavioral context: new resources default to draft unless isPublished is set, the uploadTicket is one-time, FILE is capped at 10 MB, and the unmodified uploadResult must be passed through. It stops short of describing auth/permission needs or failure 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?

Six tight sentences, front-loaded with the purpose and immediately followed by per-type requirements, then defaults, then the API reference and targeting. Every sentence carries load, though the bare API-reference URL adds little for an agent that already has the 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 no explanation, and the description covers the type matrix, the draft default, the upload flow, and campaign targeting for a 10-parameter conditional mutation. The main remaining gap is not explicitly routing the agent to the prepare-upload sibling that produces uploadTicket/uploadResult.

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 50% schema description coverage, the description meaningfully compensates: it explains the conditional coupling of type to url/text/uploadTicket/uploadResult, the HTTPS constraint, the isPublished default, and the campaignId-to-GROWSURF_CAMPAIGN_ID fallback. This adds real semantics the schema's conditional allOf alone makes hard to parse.

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

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

The description opens with a specific verb+resource ("Create a `FILE`, `LINK`, or `TEXT` resource for participants") and immediately enumerates the three subtypes, which lets an agent distinguish it from sibling tools like update_program_resource, list_program_resources, and delete_program_resource without opening a schema.

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

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

It gives clear per-type usage conditions (LINK needs HTTPS url, TEXT needs text, FILE needs uploadTicket + uploadResult) and states the draft-by-default behavior. However, it never names the obvious prerequisite sibling `growsurf_prepare_program_resource_file` for the "secure upload flow," leaving the agent to infer where uploadTicket/uploadResult come from.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds real value by spelling out the concrete side effects: deactivation, removal from the reward set, and cleanup of connected upfront-discount coupons. It omits permissions/irreversibility, so not a 5.

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

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

Three tight sentences, front-loaded with the action and its effects, then the identifier meaning, then the targeting fallback. No filler, though the return-value mention is slightly redundant given the output schema exists.

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 destructive tool with an output schema present, the description covers the action, side effects, required key semantics, and targeting default. Only permissions/irreversibility context 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 50% and campaignRewardId has no schema description, so the description compensates by defining it as the reward key. It also restates the campaignId default behavior, which is useful even though the schema already documents 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 (Delete) plus resource (campaign reward / reward config) and names the parent program, distinguishing it from list/create/update_campaign_reward siblings. The scope is unambiguous.

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

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

The description makes clear it's a destructive removal and explains the fallback target, but never says when to prefer it over alternatives like update_campaign_reward (deactivate without deleting) or when deletion is inappropriate. Usage 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, idempotentHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the return shape ({ id, success }) and the campaign-resolution fallback, but never states what is destroyed or whether the removal is reversible beyond the idempotency already annotated.

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, front-loaded sentences with no filler; the operation comes first and the targeting caveat second. The explicit return-shape note is mildly redundant given an output schema exists.

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 destructive tool whose annotations carry the safety profile and which has a full output schema, the description covers the essential targeting default and return shape. Missing only a note on failure/permission behavior, which is a minor gap.

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

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

Schema coverage is only 50% (webhookId has no schema description), and the description only says 'by id'. Its campaignId statement largely duplicates the schema's own description of the GROWSURF_CAMPAIGN_ID default, so it adds little beyond the structured field.

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 by id'), which inherently separates it from the sibling list/create/update/test webhook tools. An agent can identify the operation and its keying parameter without opening the schema.

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

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

The description gives no when-to-use guidance, no prerequisites, and never names an alternative (e.g., update vs. delete vs. test webhook). It explains parameter targeting, but that is parameter semantics, not usage 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: deleting the resource does NOT delete the underlying reusable Media Center asset, which an agent could easily assume otherwise.

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 with the destructive action stated first, then the important side-effect caveat, then the targeting rule. Nothing is redundant and no sentence is filler.

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

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

An output schema exists so return values need no explanation, and annotations cover safety semantics. Adding the media-asset preservation note and the id-fallback rule makes this nearly complete for a 2-param delete; the only real gap is the unexplained resourceId.

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 documented in the schema and the description reinforces its fallback behavior, but resourceId has no description in either place, leaving the agent to guess where the id comes from (e.g., list_program_resources). The description compensates on one param but not the other.

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 immediately scopes it by clarifying that the reusable Media Center asset survives. This separates it from the media-asset concept and from sibling deletes like delete_campaign_reward, though it never names an alternative tool by name.

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 targeting context ('Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID'), which tells the agent how to address the call, but there is no explicit when-to-use vs. when-not-to-use guidance and no pointer to update_program_resource for modification instead of deletion.

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

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

Beyond the annotations (destructive, non-idempotent, open-world), the description discloses real behavior: automatic compliance injection (company name, postal address, unsubscribe link), suppression of unsubscribed participants, the verification prerequisite with a 400 failure mode, and that delivery is only 'accepted' rather than confirmed. This is meaningful context an agent could not infer from structured fields.

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

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

The action is front-loaded in the first clause, then mode selection, then compliance/prerequisites, then targeting default. Dense but every sentence carries information; it reads as a single long paragraph rather than clearly separated clauses.

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

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

For a 7-parameter, no-required-field mutation tool with an output schema, the description covers the required pieces: mode selection, addressing, defaults, prerequisites, error behavior, and post-send semantics. Return-value documentation is correctly left to the output schema.

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

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

Schema coverage is only 57%, and the description compensates: it explains the emailType/subject+body exclusivity in prose, clarifies participantId vs participantEmail as alternatives, mentions the optional preheader that has no schema description, and confirms the campaignId 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?

The description opens with a specific verb and resource ('Send an email to a participant') and immediately names the two addressing options (participant ID or email), which clearly separates it from sibling participant tools like get_participant 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?

It gives strong context for the two mutually exclusive modes ('Provide EITHER emailType ... OR subject + body') and states the prerequisites for sending (verified team, verified custom email domain, 400 until verified). It stops short of explicit when-not-to-use exclusions in the description itself, since the unsendable template list lives in the schema.

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 that the output is HTML and may include auth attributes, but it does not clarify what those attributes do, what side effects they imply, or whether participant data becomes embedded in the snippet.

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

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

The description is a single, front-loaded sentence with no filler or redundant wording. It conveys the core action and the main optional capability efficiently.

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 nested participant object, enum choices, and the withAuthAttributes flag, the description is too thin. It does not explain what participant is for, when auth attributes should be used, or how the returned snippet relates to the embeddable element. The output schema covers return shape but not the decision-making needed for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate, but it only hints at 'embeddable element' and 'optional auth attributes.' It does not explain the participant object or provide meaning for the element enum values, leaving a significant semantic gap for the agent.

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

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

The description uses a specific verb ('Generate') and a specific resource ('HTML snippet for a GrowSurf embeddable element'), making the tool's basic purpose clear. It is distinct from the many campaign/analytics tools, though it does not explicitly differentiate itself from sibling snippet-oriented tools like client_snippets or grsf_config_snippet.

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

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

The description provides no guidance about when to use this tool versus alternatives, no prerequisites, and no exclusions. An agent is given no context about when an embeddable element snippet is the right choice compared to other snippet or integration tools.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond them: embedded reward settings do not imply a reward was earned, approved or delivered, which prevents an agent from 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 with the purpose front-loaded and no filler. The reward-semantics caveat is a useful clarification, though it occupies two of the three sentences for a point that is secondary to the call itself.

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

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

For a zero-required-param, read-only tool with an output schema and full schema coverage, the description supplies what the structured fields do not: the reward-interpretation caveat and the id-resolution rule. Only the absence of sibling routing keeps it short of complete.

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

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

Schema coverage is 100% and the parameter's own description already documents the GROWSURF_CAMPAIGN_ID fallback, so the description's restatement adds no new meaning. Baseline 3 applies when the schema carries the full load.

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 your GrowSurf campaign (program) details via REST.' An agent can tell this is a single-campaign read rather than a list, but the description never names the nearest siblings (growsurf_list_campaigns, growsurf_get_campaign_design/options/emails) to sharpen the boundary.

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

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

The only conditional given is parameter resolution ('Targets campaignId if supplied, otherwise GROWSURF_CAMPAIGN_ID'), which is invocation mechanics rather than guidance. Nothing says when to reach for this tool versus the many other campaign-scoped getters or the list 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 safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely non-obvious behavioral context: the cohort-grouping field differs by program type, null/zero must be interpreted against coverageStartAt/state/reason, and unavailable history is not evidence an action never occurred. It stops short of disclosing pagination, result size, or authorization 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?

Front-loads the core action, then layers cohort semantics, stage order, defaults, interpretation caveat, and target resolution in compact sentences. Every sentence carries actionable information with no filler.

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

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

With an output schema present, the description need not explain return values, and it covers everything else an agent needs: cohort boundary pairing, defaults for timezone/interval/window, the funnel stages, and how to read null or zero results. Complete for a six-parameter analytics query.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: the 7/30-day window applies per participant from eligibility, cohort bounds must be omitted together for the default mature cohort, and campaignId falls back to GROWSURF_CAMPAIGN_ID. This goes beyond restating 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 (Fetch) and a precisely scoped resource (strict activation for eligible participants in one enrollment cohort), and enumerates the ordered funnel stages. It does not, however, name or distinguish itself from the closely related growsurf_get_campaign_analytics sibling, leaving the agent to infer the boundary.

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

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

Offers one concrete usage rule ('Omit both cohort bounds for the latest fully matured cohort') and a fallback for campaignId, which implies intended usage. But it never states when to choose this tool over get_campaign_analytics or get_participant_analytics, nor any prerequisites or exclusions, so selection guidance 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral context beyond them: default window of 365 days with a 1825-day cap, default `interval=total`, engagement-only applicability of `timezone`/`platform`, and the `coverageStartAt`/`state`/`reason` semantics that separate measured zeroes from partial history. It does not mention auth or rate limits, but its contributions are substantive.

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 metrics, then moves efficiently through interval, include, timeframe, and targeting. It is dense and somewhat long, with minor overlap against schema text (Unix-ms date constraints restated), but nearly every sentence carries actionable information.

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

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

With an output schema present, return values need not be re-explained, yet the description helpfully clarifies conditional outputs (`series`, engagement sub-fields, previousPeriod) and default resolution for `campaignId` via GROWSURF_CAMPAIGN_ID. For an 8-parameter read tool with rich annotations and an output schema, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is already 88%, so baseline is 3. The description goes beyond it by explaining what `include` values yield (e.g. `engagement` groups unique active/sharing/repeat/retained participants by portal-view and share timing), clarifying that `timezone`/`platform` apply to engagement only, and noting the default `days=365` that the schema omits. This meaningfully supplements the parameter docs.

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

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

The description states a specific verb (Fetch) and resource (analytics for your GrowSurf program) and enumerates the metrics returned (participants, referrals, impressions, per-channel shares, affiliate revenue/commission/payout). This is clearly distinguishable from sibling analytics tools like get_campaign_activation_analytics or get_participant_analytics by scope, though it never names those siblings explicitly.

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

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

The description explains how to shape the request (pass `interval` for a series, `include` values for extra views, `days` vs explicit date window) but gives no guidance on when to choose this tool over sibling analytics tools. Usage is implied rather than stated with conditions 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 cover the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, and the description still adds real behavior: missing/unknown enum values fall back to INITIALS, stored nulls return as null while omitted fields use localized defaults, and the confirmation section is omitted when empty. It stops short of noting auth/permission requirements or error behavior, so not a 5.

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

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

The purpose is correctly front-loaded in the opening clause, but the rest is a single ~120-word run-on sentence packing in every returned field. With an output schema present, much of this enumeration duplicates structured data, making the wall of text hard to scan.

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

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

For a one-parameter read tool with full annotations and an output schema, the description is more than complete on behavior and edge cases. Its only weakness is that it over-explains return contents that the output schema already carries.

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, and the description's note that it targets campaignId when passed and GROWSURF_CAMPAIGN_ID otherwise largely restates the schema. Baseline 3 is appropriate; no new syntax or format detail is added.

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') and enumerates the exact sections returned, which cleanly separates it from sibling readers like growsurf_get_campaign (general), growsurf_get_campaign_options, and growsurf_get_campaign_emails.

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

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

Usage is only implied: the field enumeration signals this is the design-config reader, and the update counterpart (growsurf_update_campaign_design) is never named. The only explicit direction is about which id is targeted, which is parameter behavior rather than when-to-use guidance.

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

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

Annotations already establish readOnlyHint, idempotentHint, and non-destructive status, so the bar is lower. The description still adds real value: it flags that settings.sender.fromEmail is read-only and must be changed in the dashboard after domain verification, a constraint not captured by annotations or 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, front-loaded with the fetch scope, then the read-only caveat and targeting fallback. No filler, though the targeting sentence partially duplicates the 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. The description covers what is returned, a notable read-only caveat, and id resolution, which is adequate for a single-optional-param read tool.

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

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

Schema description coverage is 100% and the schema already documents the campaignId default to GROWSURF_CAMPAIGN_ID, so the description's restatement of targeting 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 resource (Emails tab configuration) and enumerates what's included: participant and admin email templates, settings, and read-only fields. It is distinguishable from the sibling growsurf_update_campaign_emails by the read-only framing, though it never names the sibling explicitly.

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

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

No statement of when to use this tool versus growsurf_update_campaign_emails or the other get_campaign_* reads. The only conditional given is which id is targeted, which is parameter behavior rather than usage 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, and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond them: it returns the full object with every field's current value and mirrors the update payload shape, which tells the agent the response is a complete, re-sendable configuration snapshot.

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

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

Two tightly written sentences, front-loaded with what is fetched and followed by the return shape and target resolution. No filler or repetition.

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

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

With an output schema present, the description need not enumerate return fields, and it correctly summarizes the shape instead. Combined with full annotation coverage and a single parameter, an agent has what it needs to invoke the call correctly, though no explicit routing guidance against sibling configuration readers is offered.

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 already documents the GROWSURF_CAMPAIGN_ID fallback, so the description largely restates what the schema provides. No additional format or resolution semantics are added beyond the 'if you pass it, otherwise' default rule.

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 named resource (Installation tab configuration for your GrowSurf program) and scopes it to embed/installation and tracking setup. It also implicitly distinguishes itself from the write counterpart by noting it returns the same shape you send back on update, so an agent can separate it from growsurf_update_campaign_installation without opening either schema.

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

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

The description explains which program is targeted (campaignId vs GROWSURF_CAMPAIGN_ID) and implies the read-before-write pairing with update, but it never states when to use this tool versus alternatives such as growsurf_client_snippets, growsurf_embeddable_element_snippet, or growsurf_update_campaign_installation. Usage is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond them: it states the response contains every field with its current value, that it targets campaignId or falls back to the GROWSURF_CAMPAIGN_ID env var, and warns that autoFulfillRewards: false does not prove a reward went undelivered — a genuine misinterpretation guard.

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, then the return shape, then the default-targeting rule and the field caveat. Dense but every sentence carries information; the parenthetical field list is slightly long but aids scope recognition.

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 usefully frames the return as update-compatible. For a single-optional-parameter read call it is essentially complete, though it says nothing about failure or permission 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?

Only one parameter with 100% schema description coverage, so the baseline is 3. The description restates the campaignId/GROWSURF_CAMPAIGN_ID fallback that the schema already documents, adding no new syntax or format detail.

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

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

States a specific verb (Fetch) and a precisely scoped resource (the Options tab configuration of a GrowSurf program), then enumerates the content domains it covers (referral triggers, anti-fraud, affiliate enrollment, notifications). This clearly separates it from siblings like get_campaign_design, get_campaign_emails, and 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: it notes the return is 'the same shape you send back on update,' which hints at the read-before-write pattern with update_campaign_options, but no alternative tool or condition is named explicitly. The autoFulfillRewards caveat is interpretive guidance, not a when-to-use rule.

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

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

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 declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine interpretive context beyond that — that a zero referralCount is consistent with CREDIT_AWARDED, and that approved/status/isFulfilled record fulfillment marking rather than delivery — which prevents real misreads of a participant record.

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 front-loaded, no filler. The middle sentence on referral/reward field semantics is dense and arguably overlaps the output schema's territory, but it is not padding.

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 shape, and annotations cover the safety profile, so the remaining job is purpose, lookup keys and targeting — all covered. Only the missing routing guidance against siblings (list vs get vs analytics/activity logs) and not-found behavior keep it from a 5.

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 are undocumented in the schema). The description compensates by stating both identifiers work as lookup keys and by restating the campaign targeting rule ('targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID'), covering all three parameters meaningfully.

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

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

Names a specific verb (Fetch), the resource (a single participant), and both lookup keys (participant ID or email address). The word 'single' implicitly separates it from the sibling growsurf_list_participants, so an agent can route without opening the 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?

Usage is only implied — 'single participant' hints this is the targeted-fetch counterpart to list_participants, and the campaign-targeting sentence gives a calling context. There is no explicit when-to-use/when-not statement and no named alternative such as list_participants or get_participant_analytics, which matters given the large sibling surface.

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 detail: the response `offset` acts as the next-page cursor and is null when exhausted, and campaign resolution falls back to an env var. Missing only things like log retention 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 dense sentences, front-loaded with the core purpose, followed by pagination mechanics and the campaign fallback. No filler, though the pagination and defaulting details make it slightly 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 values needn't be explained, yet the description still clarifies the pagination cursor semantics that agents would otherwise have to infer. Combined with the low schema coverage it covers enough for correct invocation; a brief note on what an activity log entry contains would close the remaining gap.

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

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

Schema coverage is only 20%, so the description must compensate, and it largely does: it documents the 1-100 limit range with a default of 20, the offset skip behavior, the ID-or-email alternative for identifying the participant, and campaign targeting. Only the participantId/participantEmail format details remain thin.

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 a participant's activity logs'), names the two accepted lookup keys (participant ID or email), and specifies ordering ('most recent first') and pagination model. This is clearly distinguishable from siblings like growsurf_get_participant or growsurf_get_participant_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?

The description explains the campaignId fallback to GROWSURF_CAMPAIGN_ID, which is useful context for invocation, but gives no explicit guidance on when to reach for this tool versus growsurf_get_participant or growsurf_get_participant_analytics. Usage is implied rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds non-obvious behavior: a null milestone with partial `state` means unknown rather than never-happened, the API returns 400 for unknown `include` values, and date params deliberately do not filter the base response or activation milestones. It stops short of auth or rate-limit context, but the added semantics are substantive.

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 base response contents, then include options, then filtering rules, then campaign targeting — a logical progression. It is dense and repeats the date-window constraint already in the schema, but nearly every sentence carries operational weight.

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

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

Given an output schema exists, the description needn't explain return shapes, and it correctly focuses on include semantics, filter scoping, and targeting. The anyOf participantId/participantEmail requirement is only implied ('by ID or email') rather than stated as a mutual requirement, a minor gap.

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

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

With 75% schema coverage the schema documents most params, but the description adds real meaning: the 1825-day cap and ordering constraint, that date filters scope only optional series/email data, and that `campaignId` falls back to GROWSURF_CAMPAIGN_ID. It goes beyond restating the schema, though it repeats some schema text.

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

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

States a specific verb and resource ('Fetch analytics for one participant') and pins the lookup key ('by GrowSurf participant ID or email'). The 'one participant' scope implicitly separates it from sibling campaign-level analytics tools like growsurf_get_campaign_analytics and growsurf_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 concrete operational guidance: add `activation` for the eligibility anchor, request both `activation` and `series` for covered buckets, and filter with `days`/`startDate`/`endDate`. However, it never names alternative sibling tools (e.g. participant activity logs vs. campaign analytics) or states when this tool should be chosen over them.

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, and the description goes well beyond them: it discloses what fields are returned per provider (status, confirmed email, recipient type, repair reason) and the semantics of activeProvider being null until confirmation. Rich behavioral context that the annotations could not 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?

Front-loads the core purpose, then layers output detail and targeting logic without redundancy. Slightly dense but every clause carries information; nothing reads as 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, return values need not be documented, yet the description helpfully characterizes them. Targeting defaults are covered; the only gap is the missing when-to-use guidance, which is minor for a read tool.

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

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

Schema coverage is only 33% (campaignId documented, participantId/participantEmail bare). The description compensates partially by noting the participant can be identified by ID or email and by explaining the campaignId fallback to GROWSURF_CAMPAIGN_ID, but it adds no format or validation detail for the identifier params.

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

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

States a specific verb (Get) and resource (participant's payout-destination status), plus scope (across every payout provider enabled for the program). An agent can distinguish it from the sibling growsurf_request_participant_payout_destination_confirmation purely from the description.

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?

Explains how to target the program (campaignId or GROWSURF_CAMPAIGN_ID), which is useful context, but never says when to use this versus alternatives like get_participant or request_participant_payout_destination_confirmation. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint/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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which fully cover the safety/mutation profile; the description does not contradict these. The added 'happy-path' qualifier is a useful behavioral signal that this produces a straightforward plan rather than troubleshooting edge cases (unlike growsurf_troubleshoot_referral_tracking). However, the description does not disclose what the plan contains or its limitations, beyond the happy-path scope.

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

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

The single sentence has no wasted words and is well front-loaded. But it is so terse that the tool is under-specified rather than efficiently concise. There is room to add meaningful guidance without sacrificing brevity, so the conciseness is adequate but not exemplary.

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

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

For a tool with 5 optional parameters, 3 enums, and an output schema, the description is incomplete. It does not explain how the parameters shape the generated plan, what 'happy-path' means operationally, or how this guide differs from the many sibling guide/snippet/advisor tools. The output schema mitigates some return-value uncertainty, but the description leaves too much about behavior and parameter influence unexplained.

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% with 5 parameters, so the description bears the full burden of explaining parameter semantics, but it mentions none of them. While parameter names like programType and singlePageApp are fairly self-explanatory, enum values such as 'signup_plus_qualifying_action' and 'token_in_url' are opaque and unaddressed. The description adds zero value to the input schema at a coverage level where it absolutely must compensate.

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

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

The description uses a specific verb ('Generate') with a specific resource ('GrowSurf integration plan') and scopes it as 'guided, happy-path' covering referral and affiliate. This is clear about what the tool produces. However, it does not differentiate from the very similar sibling growsurf_program_design_advisor, which likely also delivers advisory/plan guidance, so an agent could confuse the two.

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

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

There is no guidance on when to use this tool versus alternatives such as growsurf_program_design_advisor, growsurf_api_library_snippets, or growsurf_client_snippets. No exclusions, prerequisites, or context are given. The description merely states what it does, leaving the agent to infer when 'happy-path integration planning' is the right choice.

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 value beyond them: it discloses inclusion rules (switched-off rewards and unselected-group rewards appear; deleted ones do not) and warns that these settings do not imply a participant earned a reward, which prevents a common misinterpretation.

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 scoping and the inclusion/exclusion rules are front-loaded, and the earned-reward caveat follows immediately. It is a fairly dense multi-sentence block, but each sentence carries distinct information rather than padding.

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

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

With an output schema present, return-value detail is unnecessary, and the description fully covers scope, include/exclude semantics, the earned-vs-configured distinction, and targeting behavior. An agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the single campaignId parameter and its GROWSURF_CAMPAIGN_ID fallback are already documented in the schema. The description restates that targeting behavior without adding syntax, format, or edge-case detail, so the baseline 3 holds.

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 (List) and resource (configured Campaign Rewards), then precisely bounds scope: includes switched-off and non-group-selected rewards, excludes deleted rewards. It also disambiguates from a confusingly similar concept (earned reward records on participants), so an agent can distinguish it from siblings like get_participant or the reward CRUD tools.

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

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

It clearly establishes when this tool is the right source (configuration-level reward definitions) and when it is not (earned/received reward records, which belong to the participant). However, it does not explicitly name alternate tools (e.g., growsurf_get_campaign or growsurf_get_participant) that an agent should reach for instead, leaving that routing 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, 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond that: secrets are never returned, which sets expectations about the payload's sensitivity.

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

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

Two short sentences, with the resource and the parenthetical security note front-loaded and the targeting rule following. Every clause carries information; there is no filler.

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

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

An output schema exists, so return-value detail is unnecessary, and the secret-suppression note covers the one surprising aspect of the response. Nothing an agent needs to call this correctly is missing, though pagination or ordering behavior is not addressed.

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 one parameter and 100% schema description coverage, the schema fully documents campaignId, including the env-var fallback. The description merely restates that same targeting rule, adding no new syntax or format detail beyond structured data.

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

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

The description gives a specific verb and resource ('List your GrowSurf program's webhooks') and clarifies the parent-resource relationship, which distinguishes it from the create/update/delete/test webhook siblings. It stops short of explicitly naming those siblings as alternatives.

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

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

It explains the targeting rule (pass campaignId or fall back to GROWSURF_CAMPAIGN_ID) but gives no explicit when-to-use guidance, e.g. 'use before updating/deleting a webhook' or 'use create_campaign_webhook to add one.' Usage is implied by the verb, not stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description still adds real behavior detail such as the meaning of `autoDisabled` (delivery stopped after repeated failures until reconnect) and the omission rule for program-type-inapplicable integrations. It does not discuss pagination or failure modes, but the added semantics are substantive.

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

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

Front-loaded with the core action and covered integrations, then dense supporting detail. Every sentence carries information (field meanings, omission rule, read-only, connection note, targeting), though it runs a little long for a simple list 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?

An output schema exists, so return-value explanation is not strictly required, and the description still sketches the key fields. Combined with full annotation and schema coverage, an agent has what it needs to call the tool correctly; only explicit sibling routing 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% for the single `campaignId` parameter, so the schema already documents its type and default. The description only restates the fallback to `GROWSURF_CAMPAIGN_ID`, adding no syntax or format detail beyond what the schema provides — baseline 3.

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

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

States a specific verb (List) and resource (integrations) plus the exact set covered (Stripe, PayPal, Wise, Mailchimp, Slack, Zapier, Webhooks). It is clearly distinguishable from siblings like growsurf_get_integration_connect_link or growsurf_integration_guide.

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

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

Provides useful context (connection happens in the dashboard, not via the API; non-applicable integrations are omitted), which implies the tool's scope. However, it never explicitly states when to use this versus the sibling connect-link or integration-guide tools, leaving selection to inference.

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