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

Discloses substantial behavior beyond the annotations: it is an upsert (existing participants returned unchanged), it is intended for trusted direct enrollment, it explains the approval logic for isAffiliate and referredBy, and it specifies the campaignId fallback to GROWSURF_CAMPAIGN_ID. The annotations are minimal, so the description carries and meets the burden.

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 behavior, then gives the warning and affiliate rules. Every sentence contributes useful information, though the affiliate logic is dense and could be tightened slightly without losing meaning.

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

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

For an 11-parameter tool with an output schema, the description covers the critical enrollment semantics, campaign targeting, and the public-application exclusion. It does not explain referralStatus or the enrichment parameters, but the core decisions needed to invoke the tool correctly are well covered.

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

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

Schema description coverage is only 18%, so the description must compensate. It adds important semantics for email, referredBy, isAffiliate, and campaignId, especially the interaction between isAffiliate and referredBy. However, it leaves several parameters unexplained, including referralStatus, metadata, fingerprint, ipAddress, and mobileInstanceId, so compensation is only partial.

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 combination: 'Add or fetch a participant by email,' and immediately clarifies the key upsert behavior ('Existing participants are returned unchanged'). This distinguishes it from sibling participant tools like get_participant or update_participant, which are not email-based upserts.

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 when-to-use context ('trusted direct enrollment') and an explicit when-not-to-use condition ('do not use it for a public application when the program requires affiliate review'). It also gives conditional guidance for affiliate programs. It does not name a specific alternative tool to use instead, 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 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 declare destructiveHint and idempotentHint, but the description goes far beyond them by explaining what deletion removes (referrals, rewards, commissions, payout records), status semantics, 200 vs 202 differences, analyticsErasure, and the recommendation not to repeat successful rows. This is exemplary behavioral disclosure and adds substantial context not available in the structured fields.

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

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

The description is dense but every sentence earns its place: purpose, destructiveness, input constraints, response format, status meanings, async erasure, and campaign targeting. The destructive warning is front-loaded, and the flow from inputs to outputs is logical. Nothing feels redundant or decorative.

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

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

Given the tool's complexity — permanent bulk deletion, mixed identifiers, chunking, partial errors, 200 vs 202 behavior, and pending analytics erasure — the description covers every operational aspect an agent needs. The output schema and this description together give a complete picture, including edge cases like NOT_FOUND and DUPLICATE rows.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical value by clarifying that mixed participant IDs and emails are allowed, that lists may need chunking across calls, and that entries resolving to the same participant produce DUPLICATE. This supplements the schema rather than merely restating 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?

The description opens with a specific verb ('Bulk delete'), a precise resource ('participants from your GrowSurf program'), and the scope ('in one request'). It clearly differentiates this from other participant-focused tools and immediately signals permanence, so an agent can identify its purpose at a glance.

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 strong usage context: when to use bulk deletion, how to chunk lists over 200 entries across multiple calls, and which campaign is targeted by default vs. when campaignId is passed. It lacks an explicit 'do not use this when...' exclusion, but the boundary is clear enough given the identical sibling pool and the permanent nature of the operation.

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 destructiveHint=true and idempotentHint=true; the description adds context beyond those: the action applies only to a pending trigger, has a campaign targeting default, and returns { success, message }. It does not mention what happens if the delay has already elapsed, which is minor given 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?

Three short sentences, each carrying distinct value: action window, return shape, campaign targeting. There is no filler or repetition beyond the brief default-campaign note.

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

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

The description gives the core purpose and return shape, and the output schema covers the response. However, it omits the key invoke precondition that one of participantId/participantEmail is required, and does not describe behavior when the delay has already elapsed. For a simple 3-parameter tool this is a noticeable but not crippling 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 only 33%, so the description must compensate for the otherwise undocumented participantId and participantEmail parameters. It only echoes the schema's campaignId default behavior and names 'participant' generically; it never explains that either participantId or participantEmail is required, nor offers any guidance on selecting between them.

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 action ('Cancel a pending delayed referral trigger'), a target ('a participant'), and a temporal boundary ('before the delay elapses'), with a concrete use case (refund/cancellation). This distinguishes it cleanly from siblings like growsurf_trigger_referral and growsurf_refund_transaction.

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 guidance on the situation where this tool is appropriate ('before the delay elapses (e.g. on refund/cancellation)') and the default behavior for campaignId. It does not explicitly compare against sibling tools such as growsurf_trigger_referral or explain when not to use it, so it stops short of full exclusion 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 are all false and offer no behavioral detail, so the description carries the full burden. It discloses temporary/short-lived URLs, the controlled experiences captured, rejection of arbitrary URLs/HTML/JS/external targets, and the campaignId fallback to GROWSURF_CAMPAIGN_ID. No contradiction with annotations.

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

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

Four sentences, front-loaded with the core purpose, followed by output nature, exclusions/alternative, and parameter targeting. Every sentence earns its place; no fluff or redundant content.

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

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

For a one-optional-parameter tool with an output schema, the description covers when to call, what it does, what it does not do, and how campaignId targets. The output schema handles return-format details, so no essential 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 description coverage is 100%, and the schema's campaignId description already explains the default behavior and the create_campaign relationship. The tool description restates the default-targeting behavior but adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource: capture temporary GrowSurf preview screenshots, and narrows scope to the controlled referrer Window and referred-friend experience. It clearly distinguishes itself from the many campaign/config/analysis siblings and explicitly notes this does not prove the user's installed site, preventing confusion with browser automation.

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

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

Explicitly defines when to use: 'after the user explicitly asks for screenshots or screenshot proof.' It also names an alternative for a different need ('use browser automation for that') and lists unsupported input categories, giving both positive and negative 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 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 already indicate this is a mutating, non-idempotent operation. The description adds valuable behavior: integrations and credentials are not copied, active rewards are cloned, and the result is a draft program. This goes beyond the structured annotations.

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

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

Three sentences with no filler: the main action is front-loaded, the copy caveat is explicit, and the parameter default is clearly stated. Every sentence earns its place.

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

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

For a one-optional-parameter clone operation with an output schema available, the description covers the essential behavior, the selective copying, and the default target. Nothing an agent needs 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 100% and the schema already documents the default behavior and use with growsurf_create_campaign. The description mostly restates this targeting rule, adding little new meaning beyond the schema.

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

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

States a specific verb ('Clone'), the resource ('GrowSurf program/campaign'), and the concrete result ('a new DRAFT program'). This distinguishes it from sibling creation/update tools and makes its purpose immediately clear.

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

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

The description explains what the tool does and how the optional campaignId default behaves, but it never says when to choose cloning over creating or updating a program. No alternatives or exclusion criteria are mentioned.

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

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

The description goes far beyond the annotations (destructiveHint=true, openWorldHint=true) by detailing the 14-day trial, one-time key delivery, unrecoverable key loss, email-verification lock with 403 EMAIL_NOT_VERIFIED_ERROR, 7-day deletion of unverified accounts, key rotation after dashboard sign-in, and rejection of personal/disposable emails. It also describes post-creation steps and error codes, fully aligning with the annotations.

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

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

The description is long, but it is front-loaded with purpose and preconditions, then flows through workflow, error handling, and caveats. Each sentence contributes meaningful operational detail; while it could be tightened, there is no filler or redundancy.

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

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

The description covers prerequisites, alternatives, error codes, recovery flows, key lifecycle, and account-deletion behavior, providing everything an agent needs to execute the account-creation workflow end-to-end. Since an output schema exists, the absence of return-value detail is acceptable.

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

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

Schema description coverage is 0%, so the description must compensate. It does for the email parameter, explaining verification requirements and domain restrictions, but it adds no semantic detail for company, lastName, or firstName beyond their self-evident names. This is adequate for the most critical parameter but leaves the others to inference.

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 precise verb and resource: 'Create a brand-new GrowSurf account and return an API key.' It further distinguishes itself by noting it is the only tool in the set that does not require GROWSURF_API_KEY, making it unmistakable among the sibling tools.

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

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

Explicitly states when to call: only after owner approval and acceptance of ToS/Privacy Policy. It also provides alternatives—using the hosted MCP server when key storage is impossible, and growsurf_resend_team_owner_verification_email for lost verification emails—so an agent knows when not to use this tool and what to do instead.

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 carry only a minimal safety profile (readOnlyHint=false, destructiveHint=false). The description adds extensive behavioral context: the program is 'created in DRAFT status owned by the credential's bound team,' `currencyISO` 'is immutable after creation,' `goal` is 'set here or not at all,' and starter rewards are 'switched off so it awards nothing yet.' It also tells the agent how to use the response id as `campaignId` for subsequent tools.

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?

At roughly 200 words the description is long, but it is heavily front-loaded — the first sentence states the core action and the rest proceeds through constraints in logical order. It is slightly repetitive with the schema's rewards and goal descriptions, though it adds the agent-facing instruction to ask the person for the incentive. Every section earns its place for a tool with this many lifecycle constraints.

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

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

The output schema covers return values, and the description covers everything else an agent needs to invoke this correctly: the single required param, the DRAFT state, ownership, currency immutability, set-once goal behavior, the editor-config exclusion, and the id-to-campaignId handoff. The only notable omission is the semantic difference between REFERRAL and AFFILIATE types, which the enum alone does not explain, but this does not block 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 only 29%, so the description must compensate. It adds critical guidance for the decision-heavy params: 'leave `rewards` out unless they named an amount,' `currencyISO` 'defaults to `USD` and is immutable,' and `goal` is 'set here or not at all.' However, name, companyName, and companyLogoImageUrl receive no description in either the schema or the description, leaving a small gap for those three optional 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?

The description opens with a specific verb+resource: 'Create a new GrowSurf program (campaign) pre-populated with type-appropriate starter content...' The 'pre-populated with starter content' qualifier and 'optionally with inline rewards' distinguish it from sibling creation tools like growsurf_create_campaign_reward and growsurf_clone_campaign. The title alone is generic, but the description fully disambiguates the tool.

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

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

The description explicitly states what this tool is not for: 'Editor-tab config (design, emails, options, installation) is not accepted here. Fetch and review those config sub-resources after creation, then patch only what needs to change.' It also flags the prerequisite difference from siblings with 'Does NOT require GROWSURF_CAMPAIGN_ID,' and the schema's goal field routes follow-up changes to growsurf_update_campaign_design. This is explicit when/when-not guidance naming the alternative workflow.

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 this is a mutating, non-idempotent, non-destructive operation, and the description aligns with that. The description adds useful behavioral context about program-type compatibility and campaignId fallback. It does not disclose validation side effects, auth requirements, or what happens on type mismatch, but given annotation coverage the additional context is adequate.

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

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

The description is compact and front-loaded: the first sentence states the purpose, the second gives the most important constraint, and the third explains campaign targeting. Every sentence earns its place with 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?

Despite having an output schema, the tool has 23 parameters, nested objects, and many type-conditional fields, yet the description only explains two aspects. An agent would still be uncertain about which fields are required for a given reward type, how `event` relates to reward types, or what `commissionStructure` needs for AFFILIATE rewards. The description is not complete enough for correct invocation of such a complex 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 only 22%, so the description must compensate. It does add meaning for `type` (compatibility with program type) and `campaignId` (default behavior), but the other 21 parameters—including `event`, `value`, `referredValue`, `commissionStructure`, `isUnlimited`, and many more—receive no description-level guidance. This is a substantial gap for a tool with many conditional fields.

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

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

The description opens with a clear verb and object: 'Create a new campaign reward (reward config) on your GrowSurf program.' This distinguishes the tool from sibling update/list/delete reward tools. The added note about type compatibility and campaignId targeting further clarifies exactly what the tool creates and where.

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: type must match the program type, and campaignId defaults to GROWSURF_CAMPAIGN_ID when omitted. However, it does not explicitly say when to use this tool versus update_campaign_reward or list_campaign_rewards, nor does it state exclusions or prerequisites such as needing an existing program.

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

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

The description adds meaningful behavior beyond annotations: `secret` is write-only, signs deliveries via the GrowSurf-Signature HMAC header, and is never returned. It also clarifies a non-obvious default: omitting `events` subscribes the webhook to no events. These details materially improve an agent's understanding of side effects and security 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?

Three focused sentences carry a high information density with no filler. The most important call constraint (`payloadUrl` required) is front-loaded, and the write-only secret behavior is explained in a compact, useful way.

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 output schema exists and the annotations are simple, the description covers the key invocation concerns: required parameter, event subscription semantics, secret handling, and campaign targeting. The only small omission is clarifying the default or effect of `isEnabled`, but this is minor and likely covered by 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 description coverage is only 40%, so the description must compensate. It explains `payloadUrl` as required, `events` as the subscribed event list with an omit default, `secret` as write-only signing material, and `campaignId` as the targeting override. Only `isEnabled` is left entirely to the schema's bare boolean type, which is a minor gap.

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

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

The description begins with a specific verb and resource: 'Add a webhook to your GrowSurf program.' This clearly distinguishes the create action from sibling tools like update, delete, list, and test webhooks. The name and title are not merely restated; the description adds the domain object and action context.

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

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

The description gives clear context for when to use this tool: creating a webhook subscription for a GrowSurf program. It also explains the campaignId targeting rule, including the GROWSURF_CAMPAIGN_ID default. However, it does not explicitly exclude modifying or removing existing webhooks via update/delete siblings.

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

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

Annotations confirm mutation (readOnly=false) and no idempotency. The description adds that it may create or fetch a participant, uses direct enrollment, and targets campaignId by default. It does not disclose auth needs, rate limits, or consequences beyond participant creation.

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 main action front-loaded and no filler. 'via GrowSurf REST' is arguably redundant, but overall it is compact and readable.

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 overall flow, trust caveat, and campaign targeting are covered, and an output schema exists so return values need not be spelled out. However, with 11 parameters and minimal schema descriptions, important inputs like mobileInstanceId are not explained, leaving an agent to guess their role.

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 18%, so description must compensate, but it only elaborates campaignId (repeating schema) and the isAffiliate trust context. The other 9 parameters (email, mobileInstanceId, referralStatus, etc.) remain effectively 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?

Description states a specific compound operation: create/fetch a participant then create a participant-scoped mobile SDK token. It clearly identifies the resource (mobile SDK token) and separates it from sibling participant/campaign tools.

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

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

Gives an explicit when-not: trusted direct enrollment only, avoid public apps requiring affiliate review. It lacks a named alternative, so it doesn't fully route to another tool, but it provides concrete usage context and the campaignId default behavior.

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 convey readOnly=false, idempotent=false, and destructive=false. The description adds meaningful behavior beyond those annotations: new resources default to draft unless isPublished is set, campaignId falls back to GROWSURF_CAMPAIGN_ID, and FILE uploads require an unmodified upload result. This gives an agent actionable expectations without contradicting the annotations.

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

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

Four sentences carry a dense but well-organized set of facts: what the tool creates, type-specific requirements, the FILE upload prerequisite, and default behavior. It is front-loaded with the core purpose and wastes no words.

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

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

For a complex tool with 10 parameters, conditional requirements, and an output schema, the description covers the critical decision points: which fields are required per type, the FILE upload workflow, campaign targeting, and publishing defaults. The presence of an output schema means return values need not be described. Nothing an agent needs to call this 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 coverage is only 50%, but the description compensates by explaining the role of type, url, text, uploadTicket, uploadResult, campaignId, and isPublished. It clarifies which parameters apply to which resource type, which is not fully evident from the raw schema. It does not mention title, category, or description, but those are relatively self-explanatory and the schema documents some of them.

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 ('Create') and a clear resource ('program resource'), and further distinguishes among the three resource types (FILE, LINK, TEXT). It is immediately distinct from sibling tools like growsurf_update_program_resource or growsurf_list_program_resources.

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

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

The description provides explicit conditions for each resource type: LINK requires HTTPS url, TEXT requires plain text, and FILE requires calling growsurf_prepare_program_resource_file first and passing uploadTicket/uploadResult unchanged. It also explains the campaignId default and draft default, though it does not explicitly mention alternatives such as updating or deleting an existing resource.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds genuinely new behavioral context: delete means deactivation plus removal from the reward set plus cleanup of connected upfront-discount coupons. It also discloses the { id, success } return shape. No contradiction with annotations — the key-based targeting aligns with idempotentHint.

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 zero waste: the verb-and-resource statement is front-loaded, followed by side effects, then parameter and return behavior. Every sentence carries distinct information that earns its place for a destructive operation.

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

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

For a destructive tool, the description covers what gets destroyed (coupons cleaned up), the targeting fallback, and the return value, while the existing output schema handles return structure. A minor gap is the effect on participants or referrals already holding the reward, and reversibility is not addressed, but nothing essential to invoking the tool correctly is missing.

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

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

Schema coverage is 50%: campaignId has a detailed schema description but campaignRewardId has none. The description compensates by defining campaignRewardId as 'the reward key' and restating the campaignId targeting/default rule, adding meaning beyond the bare property names. It does not cover every edge but addresses the critical 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 the specific verb 'Delete' plus the resource 'campaign reward (reward config)', where the parenthetical disambiguates a reward config from other reward concepts. Among the many delete siblings (delete_campaign_webhook, delete_program_resource), this unambiguously identifies the target resource. No ambiguity about what is being deleted.

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 the operational semantics (reward is deactivated, removed from the reward set, coupons cleaned up) so an agent understands what 'delete' actually entails in this system. It also clarifies targeting behavior via campaignId with its GROWSURF_CAMPAIGN_ID default and how to route to a newly created campaign. It does not explicitly contrast with update_campaign_reward for cases where only a deactivation is desired, so no explicit exclusions are given.

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

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

Annotations already convey destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds value beyond annotations by disclosing the return shape ({ id, success }) and the campaignId fallback behavior. It aligns with the destructive annotation and adds contextual details without contradiction.

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

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

The description is three brief, purposeful sentences. It front-loads the tool's core purpose, then adds return-value and targeting details. Every sentence earns its place, with no repetition or filler.

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

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

For a two-parameter destructive delete operation, the description is complete: it identifies the resource, explains id targeting and campaign selection, notes the default campaign fallback, and mentions the return value. Output schema and annotations cover the remaining structural and safety details, leaving no significant 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 only 50%: campaignId is well documented, but webhookId lacks any schema description. The tool description partially compensates by stating 'by id' and explaining campaignId targeting and its default to GROWSURF_CAMPAIGN_ID. This clarifies the role of both parameters, though webhookId meaning remains implicit.

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 ('Remove'), resource ('a webhook from your GrowSurf program'), and the identifying key ('by id'). It is clear and actionable, though it does not explicitly distinguish itself from sibling webhook tools like create/update/list/test, leaving some differentiation to the tool name and verb choice.

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

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

The description implies when to use the tool: when a webhook needs to be removed by id. However, it provides no explicit guidance on when not to use it or which alternative sibling (e.g., update_campaign_webhook) should be chosen instead. The campaignId targeting behavior is useful usage context but does not address tool selection.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, and the description's 'Delete' is consistent with these. The description adds genuine value beyond the annotations by clarifying that the reusable Media Center asset is preserved, which is a meaningful behavioral disclosure not captured in the structured fields. No contradiction found.

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

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

Three short sentences with the primary action front-loaded. The Media Center clarification earns its place and the targeting note is compact. Slightly more structure could be added but there is no wasted prose.

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

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

For a destructive 2-parameter tool with an output schema present, the description is reasonably complete, but the resourceId parameter is left undefined in both schema and description, which an agent needs to invoke the tool. The description does not mention what the response looks like or any prerequisites, though the output schema partially mitigates this.

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 well-described in the schema but resourceId has no description. The tool description reinforces campaignId targeting but does not explain what resourceId refers to or where to obtain it, so it only partially compensates for the undocumented parameter. With half the parameters lacking schema detail, more compensation was needed.

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+resource ('Delete a participant resource from your GrowSurf program') and adds a distinguishing behavioral note (does not remove the reusable Media Center asset), which separates it from the related create/update/list program resource siblings. It could be stronger by naming sibling tools explicitly, but the purpose 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 explains the campaign targeting behavior ('Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID') which is useful context, but it gives no guidance on when to choose this tool over alternatives like growsurf_delete_campaign_reward or when NOT to use it. Usage context is implied rather than explicit.

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

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

Beyond the annotations (readOnly=false, destructiveHint=true, idempotent=false), the description discloses compliance handling, automatic unsubscribe suppression, the 400 error until verification, and that the email is only accepted for delivery. This gives the agent accurate expectations for side effects and prerequisites without contradicting the annotations.

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

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

The description is dense but every sentence adds operational value: mode selection, compliance behavior, prerequisites, error behavior, delivery semantics, and campaign targeting. The most important usage instruction is front-loaded.

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

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

For a 7-parameter, conditional tool with no required fields in the schema, the description explains the key branching constraints, prerequisites, default campaign targeting, and async acceptance. The output schema supplies return details, so no critical 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 descriptions already cover body, subject, emailType, and campaignId; the tool description adds the participant-by-ID-or-email contract and the optional preheader role. It doesn't define preheader semantics or email formats in detail, but combined with the oneOf schema constraints an agent has enough to construct valid calls.

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 (by GrowSurf participant ID or email)' and immediately defines the two modes (template or free-form). This makes it clearly distinct from sibling tools like growsurf_update_campaign_emails (configuration) and growsurf_trigger_referral (side-effect trigger).

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

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

It explicitly tells the agent when to provide emailType versus subject+body, and states that sending depends on team verification and a verified custom email domain. It doesn't name alternatives among siblings or formalize exclusions, but the choice-of-input guidance is concrete and sufficient for selecting this tool and its call form.

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 cover read-only, idempotent, and non-destructive behavior. The description adds a meaningful caveat beyond that: embedded reward settings do not prove individual rewards were earned, approved, or delivered, and the affected participant should be read instead. This is valuable behavioral context not present in the annotations.

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

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

The description is compact and front-loaded: the core action is stated first, followed by a critical reward-setting caveat and the campaign targeting rule. No redundant or self-evident content is included.

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

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

For a simple one-parameter, read-only tool with an output schema and strong annotations, the description is complete enough. It covers what the tool fetches, how the target campaign is chosen, and an important interpretation caveat about reward settings.

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

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

Schema description coverage is 100%, and the schema already explains campaignId, its default to GROWSURF_CAMPAIGN_ID, and the use of ids from growsurf_create_campaign. The description restates the default behavior but adds no new parameter-level meaning.

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

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

The description gives a clear verb and resource: 'Fetch your GrowSurf campaign (program) details via REST.' It distinguishes the tool as a single-campaign getter, but 'details' is somewhat general and does not explicitly disambiguate it from sibling resources like get_campaign_design, get_campaign_emails, or get_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: call this when you need the core campaign/program details for a specific campaign. It provides the campaignId/fallback selection logic but gives no explicit guidance on when to prefer this over list_campaigns, get_campaign_analytics, or update_campaign.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat those. It adds valuable behavioral details: the distinction between referral and affiliate grouping, the ordered stages, and the observation window. It also warns that unavailable history does not mean an action never happened, which is critical for interpreting data. The only minor gap is not describing pagination or limits, but for a read-only analytics call, this is adequate.

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

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

The description is dense with important details but is organized logically: purpose, group-by, stages, observation window, cohort bounds default, coverage caveat, and targeting default. Some redundancy with the schema exists (e.g., cohort bounds), but the added context is not superfluous. It could be slightly more concise but remains focused.

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 an output schema (mentioned as exists), so return structures are covered there. The description covers all critical aspects: cohort definition, grouping logic, stages, observation window, defaults, and interpretation caveats. For a read-only analytics tool with no required parameters, this is comprehensive and leaves no major ambiguity 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?

The schema already provides detailed descriptions for all parameters (100% coverage). The description adds meaning by explaining that cohortFrom/cohortTo define eligibility cohort bounds and that omitting them gets the latest matured cohort, which is not in the schema. It also clarifies the meaning of observationWindowDays by stating it is 'days after eligibility'. Thus it goes beyond the schema for some parameters.

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

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

The description clearly states the specific verb 'Fetch' and the resource 'activation analytics for eligible participants in one enrollment cohort'. It distinguishes itself from sibling tools like growsurf_get_campaign_analytics by focusing on activation funnel stages and cohort grouping. The stages are enumerated, so an agent knows exactly what data to expect.

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

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

The description provides explicit guidance on when to use this tool versus alternatives, such as referring to sibling tools like growsurf_get_campaign_analytics for broader analytics. It also explains critical usage context: cohort bounds omission for the latest matured cohort, the need to read coverageStartAt and state before interpreting nulls, and the default targeting behavior.

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

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

Annotations already mark the tool readOnly, idempotent, and non-destructive; the description adds genuinely useful behavioral context beyond that: engagement counts may be partial or unavailable, coverageStartAt/state/reason distinguish measured zeroes, counts may differ from other analytics tools, timezone/platform apply only to engagement, and campaignId falls back to GROWSURF_CAMPAIGN_ID. There is no contradiction with annotations.

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

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

The description is dense but every sentence earns its place. It front-loads purpose and troubleshooting routing before parameter details, and it avoids filler or repetition of the schema. The structure flows from what the tool does, to when not to use it, to how to shape the request.

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

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

For an 8-parameter read-only tool with an output schema and strong annotations, the description covers all call-relevant behaviors: target campaign fallback, optional include values, engagement semantics, timeframe selection, and interval behavior. The output schema can carry return-value details, so nothing essential is missing.

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

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

With 88% schema description coverage, the baseline is 3, but the description adds substantial meaning: it explains comma-separated include values, what engagement groups and its state fields mean, that timezone/platform only affect engagement, days default/max versus startDate/endDate windows, and how to use campaignId from growsurf_create_campaign without restarting. This goes well beyond the input schema.

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

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

The description opens with a specific verb and resource: 'Fetch analytics for your GrowSurf program' and enumerates the metric categories returned. It also routes definitional and discrepancy questions to growsurf_troubleshoot_referral_tracking, which helps distinguish it from that sibling, though it does not explicitly differentiate from growsurf_get_campaign_activation_analytics 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 gives an explicit when-not: for metric meanings or count mismatches, call growsurf_troubleshoot_referral_tracking with symptom 'numbers_do_not_match' rather than guessing. It also explains conditions for interval, include, engagement, and campaignId fallback. It stops short of stating when to prefer this over activation analytics or participant analytics, but the guidance is otherwise clear.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description goes well beyond this by disclosing enum fallback behavior for `participantAvatarStyle`, omission of the confirmation section when no fields are stored, null versus omitted field handling, and localized defaults. These are behavioral traits an agent cannot infer from the annotations alone, making the description highly transparent.

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 longer than average, but every sentence conveys essential behavior: field inventory, enum values and fallback, null semantics, section omission, and campaign targeting. It is front-loaded with the core action and resource, and code identifiers are used precisely to avoid ambiguity. It loses one point only because the null/default behavior could have been compressed without losing clarity.

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

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

For a read-only getter with one optional parameter and an output schema present, the description covers everything needed to invoke it correctly: what fields are returned, enum valid values and default, null behavior, omitted-section behavior, localized defaults, and campaign selection. No critical operational detail is missing.

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

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

The input schema already provides 100% coverage for the single `campaignId` parameter, including its default and how to obtain it from growsurf_create_campaign. The description restates the targeting default but does not add new parameter semantics beyond the schema. Per the rubric, baseline 3 is appropriate when the schema carries the 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?

The description opens with a specific verb and resource: 'Fetch the configured design fields for your GrowSurf program.' It enumerates the exact field groups returned (GrowSurf Window content, colors, sharing sections, avatar styles, Claim Offer Popup, login copy, payout confirmation copy, country labels), which unambiguously distinguishes it from sibling tools like growsurf_get_campaign or growsurf_get_campaign_emails. The inclusion of specific code paths such as `participantAvatarStyle` and `countryLabels` removes any ambiguity about scope.

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

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

The primary use case is implied by the purpose: call this when you need the read-only design configuration of a GrowSurf program. The description does clarify the campaign targeting behavior ('Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID'), which is useful operational guidance. However, it does not explicitly state when to prefer this over alternatives or when not to use it, leaving the agent to infer routing from the tool name and sibling list.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it returns the full object with every field and current value, the shape matches the update payload, and the campaignId defaults to GROWSURF_CAMPAIGN_ID when omitted. No contradiction with annotations.

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

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

Three tightly written sentences with no wasted words. The core action and scope are front-loaded, followed by the return shape and defaulting behavior. Every sentence adds necessary information.

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

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

For a simple read-only tool with one optional parameter, full schema coverage, an output schema, and safety-related annotations, the description is complete. It tells the agent what is returned, how the parameter behaves, and how the result relates to updates. Nothing essential is missing.

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

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

Schema description coverage is 100% for the single campaignId parameter, and the schema already explains the default behavior and the relationship to growsurf_create_campaign. The description repeats the defaulting behavior but does not meaningfully add beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Fetch') and a specific resource ('Emails tab configuration for your GrowSurf program'), and clarifies the scope as participant and admin email templates and settings. It clearly differentiates this read tool from related siblings like growsurf_get_campaign and growsurf_update_campaign_emails by naming the exact configuration area and noting the returned object is the same shape used on update.

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

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

The description clearly establishes this tool is for reading the current Emails tab configuration, and the phrase 'the same shape you send back on update' implicitly points to growsurf_update_campaign_emails as the companion write tool. It does not explicitly name alternatives or list when not to use it, but the usage context is clear enough for an agent to select it correctly.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond that: it returns the full object in the exact shape used for update and describes the default campaignId behavior (GROWSURF_CAMPAIGN_ID). No contradiction with annotations.

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

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

Three short, purposeful sentences: what it fetches, what it returns and how that relates to updates, and the parameter targeting default. Every sentence earns its place, and the most important information is front-loaded.

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

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

For a simple, read-only getter with one optional parameter and an output schema, nothing important is missing: the resource, response shape, and default behavior are all covered. An agent can invoke it correctly without guessing.

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

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

Schema coverage is 100% for the only parameter. The description repeats the defaulting behavior already stated in the schema and adds little extra semantic meaning. This sits at the baseline for full schema coverage.

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

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

Uses the specific verb 'Fetch' with a clearly defined scope: the Installation tab configuration (embed/installation and tracking setup). This sets it apart from sibling getters like growsurf_get_campaign_design or growsurf_get_campaign_emails, though it doesn't explicitly name them.

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

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

Makes the context clear: call this when you need the Installation tab configuration for a GrowSurf program. The phrase 'same shape you send back on update' naturally links it to update_campaign_installation. It doesn't explicitly list exclusions, but the purpose is clear enough for the agent to choose this over sibling getters.

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

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

Beyond the readOnly and idempotent annotations, the description reveals the full-object return shape, round-trip compatibility with the update operation, the autoFulfillRewards interpretation caveat, and the default target behavior. This adds meaningful operational 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, each earning its place: the purpose and contents, the return shape and update symmetry, and a non-obvious interpretation caveat plus targeting default. The core purpose is front-loaded with no filler.

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

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

For a read-only getter with one optional parameter, an output schema, and safety annotations, the description fully covers target selection, return shape, and a key interpretation pitfall. Nothing critical is missing.

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

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

Schema coverage is 100% and the optional campaignId parameter already has a thorough description including default behavior and its use with growsurf_create_campaign. The prose description only restates the default targeting behavior, adding no new semantic information.

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

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

Description uses specific verb 'Fetch' and resource 'Options tab configuration', enumerating concrete contents such as referral triggers, anti-fraud lists, notifications, and behavior options. This clearly distinguishes it from sibling getters like get_campaign_design and 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?

It provides clear context: use this to read the Options tab configuration, and it explains how campaignId targeting works. It doesn't explicitly name alternatives or exclusions, but the domain is specific enough that an agent can infer when to select this tool.

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

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

Annotations already mark readOnly, idempotent, non-destructive, but the description adds significant behavioral context: it explains the program-check that returns connected/enabled/autoDisabled status, the fallback programVerified=false behavior, and integration-specific applicability (Tango Card only for referral, Wise only for affiliate). It describes exactly what the result reveals and how it should influence agent action, going well beyond the annotations.

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

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

The description is long but front-loaded with the essential purpose and usage, then covers edge cases. Each sentence contributes new information (parameter notes, return behavior, program constraints) rather than repeating schema or annotations. It could be slightly trimmed to improve scannability, but all content is relevant.

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

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

The description covers everything an agent needs to correctly invoke this tool: when to use, how to pass parameters, what the response contains (including status flags), fallback behavior, and program-specific restrictions. With an output schema present, it doesn't need to detail return formatting. The combination of output schema and this description leaves no 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 100% for both parameters, so baseline is 3. The description adds value by clarifying camelCase keys (constantContact, helpScout), the default for campaignId (GROWSURF_CAMPAIGN_ID), and program-specific applicability of certain integrations. This goes beyond the schema's basic descriptions and helps avoid mis-selection.

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

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

The description clearly states it returns a dashboard link that opens an integration's connect panel, with specific action verbs and resource. It gives concrete example user intents (connect Stripe, set up PayPal, send Tango Card) that distinguish it from other integration-related tools like list_integrations. This is a specific, non-tautological purpose.

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

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

Explicitly states 'Use this whenever a user says they want to connect an integration' and provides trigger examples. It also explains when NOT to use it (connections happen in dashboard, not via API) and the behavior of the program-check (skip handing over unneeded links). While it doesn't name sibling alternatives, it gives complete contextual guidance for when this 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?

Annotations already declare readOnly/idempotent/non-destructive behavior; the description adds valuable field-level semantics, including that referralStatus describes credit to the referrer, zero referralCount can coexist with CREDIT_AWARDED, and rewards fulfillment fields are not delivery confirmation. It also discloses how campaignId targets the request.

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 with no filler. The primary purpose is front-loaded, the field-semantics caveats are grouped logically, and the sibling routing/default behavior closes the description 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?

For a single-object read with an output schema and read-only annotations, the description covers every invocation decision: identity lookup, campaign scoping, ID discovery, and tricky return-field semantics. Nothing needed to call it correctly is missing.

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

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

Schema coverage is low (33%), so the description compensates by identifying participantId and participantEmail as the two lookup keys and explaining campaignId's default behavior. It doesn't give formats or constraints, but each parameter's role and selection condition are clear.

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 precise action ('Fetch a single participant') and the two lookup keys (participant ID or email address). The 'single' qualifier cleanly distinguishes it from growsurf_list_participants and other participant-specific siblings.

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

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

Explicitly directs the agent to growsurf_list_participants when a participant ID is unknown, and explains campaignId's optional targeting versus the GROWSURF_CAMPAIGN_ID default. It doesn't enumerate exclusions against analytics/activity-log siblings, but the context is clear enough for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to cover safety. It adds valuable behavioral details beyond annotations, including the offset-as-cursor pagination behavior, the default limit, and the campaignId fallback to GROWSURF_CAMPAIGN_ID. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and includes all necessary operational details without redundancy. Every clause adds value, covering lookup methods, ordering, pagination, defaults, and campaign targeting.

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

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

For a read-only list tool with annotations covering safety and an output schema existing, the description is nearly complete. It covers pagination, defaults, and campaign targeting, but does not explicitly state that at least one of participantId or participantEmail is required (though the anyOf schema implies it). This minor gap keeps it from a perfect score.

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

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

Schema coverage is only 20% (only campaignId has a description), so the description must compensate. It thoroughly explains limit and offset semantics, including default values and cursor usage, clarifies participant lookup methods, and describes campaignId behavior. This goes well beyond the sparse schema.

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

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

The description clearly states the verb 'List' and the resource 'participant's activity logs', and specifies lookup by participant ID or email, most recent first, with pagination. It is specific enough to distinguish from siblings like growsurf_get_participant or growsurf_list_participants, though it does not explicitly name 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 provides usage context such as pagination parameters, default limit, and campaignId targeting, but does not mention when to prefer this tool over alternatives like growsurf_get_participant_analytics. The usage is implied rather than explicitly contrasted with siblings.

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

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

Beyond the readOnly/idempotent annotations, the description adds valuable behavioral detail: base response is all-time, null milestones mean 'unknown' not 'never happened', date-window parameters only affect optional series/email data, and campaign targeting falls back to GROWSURF_CAMPAIGN_ID. This is precisely the kind of context that prevents misinterpreting returned analytics.

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

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

The description is dense but every sentence contributes: base scope, include options, null semantics, series behavior, date filtering, and campaign targeting. It is front-loaded with the core purpose and then layers detail logically without fluff.

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

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

For a read-only analytics tool with an output schema, this description covers the key decision points: how to identify the participant, what optional includes exist, how null values should be interpreted, how date filters behave, and which campaign scope is used. No critical calling 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 75%, and the description compensates by explaining the meaning of 'include' values, how date-window parameters interact with optional data, and the campaignId fallback behavior. It adds meaning beyond the schema descriptions, especially regarding activation milestones and null-state interpretation.

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 analytics for one participant by GrowSurf participant ID or email.' It clearly distinguishes from campaign-level analytics and general participant tools by scoping to one participant's analytics and listing what the response includes.

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

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

The description clearly implies when to use this tool: to get analytics for a single participant by ID or email, with optional activation and series data. It does not explicitly name alternatives or exclusion conditions, but the scope is specific enough for an agent to differentiate it from sibling tools like growsurf_get_campaign_analytics or growsurf_get_participant.

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

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

The annotations already declare readOnlyHint and idempotentHint, and the description adds substantial behavioral detail beyond them: it reports per-provider status, confirmed email, legal recipient type, repair reason, and explains the meaning of activeProvider (null until confirmation). This gives an agent an accurate model of what the call returns and how the data behaves without contradicting the annotations.

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

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

The description is information-dense but every sentence earns its place: it defines the resource, the lookup modes, the per-provider result fields, the activeProvider semantics, and the campaignId fallback. It is front-loaded with the main purpose and contains 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?

Given an output schema exists, the description doesn't need to re-enumerate return values, and it still covers the essential input modes, provider scope, and fallback behavior. The safety profile is already covered by annotations, making this contextually complete for correct invocation.

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

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

Schema description coverage is low (only campaignId is described), but the description compensates by clarifying that participantId and participantEmail are alternative lookup keys and that campaignId defaults to GROWSURF_CAMPAIGN_ID. It adds meaning beyond the bare schema property types, though it could have provided more detail on expected formats or precedence between the two identifiers.

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

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

The description names a specific verb ('Get') and resource ('a participant's payout-destination status'), and further specifies lookup by GrowSurf participant ID or email. It is clearly distinct from sibling tools like gets participant profile, analytics, or activity logs, so an agent can select it without confusion.

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 target a campaign ('Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID') and the two accepted lookup keys. It gives clear operational context but does not explicitly state when to prefer this tool over alternative participant-related tools, so it stops short of a full when/when-not guide.

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 cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds meaningful behavioral context by specifying placement in the <head> and the ordering requirement before the GrowSurf Universal Code — a non-obvious constraint that could break the integration if ignored.

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

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

A single sentence with zero filler: the verb and resource are front-loaded, and the parenthetical placement instruction earns its place. There is no redundancy with the title or annotations.

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

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

For a tool with 7 parameters, 0% schema coverage, and no parameter documentation, the description is too thin. Even though an output schema exists to cover return values, an agent cannot reasonably decide how to set enableParticipantAutoAuth, affiliateJoin, useCampaignIdPlaceholder, or how the hash should be computed, making the tool under-specified 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?

With 0% schema description coverage and 7 parameters, the description carries the full burden of explaining parameters, but it mentions none of them — hash, email, campaignId, affiliateJoin, useCampaignIdPlaceholder, enableParticipantAutoAuth, and includeAutoAuthCommentHeader are all undocumented. The description does nothing to compensate for the schema gap.

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

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

The description uses a specific verb ('Generate') with a concrete resource (the <head> snippet for participant auto-auth) and states the exact mechanism (window.grsfConfig). It also gives installation context ('place before the GrowSurf Universal Code'), making it clearly distinguishable from siblings like growsurf_client_snippets or growsurf_embeddable_element_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 implies the use case by naming participant auto-auth and the placement constraint relative to the Universal Code, which gives the agent situational context. However, it never explicitly contrasts this tool with alternatives (e.g., when to use this vs. growsurf_client_snippets or growsurf_participant_auth_hash) and provides no exclusions.

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

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

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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds meaningful behavioral context beyond the annotations by explaining that this returns configured reward settings, not earned/received rewards, and by noting the campaign targeting fallback. This is useful semantic behavior not present in the structured fields.

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

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

The description is three short sentences with no redundant phrasing. The core purpose is front-loaded, the critical exclusion is stated clearly, and the targeting behavior is explained in the final sentence. Every sentence earns its place.

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

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

For a simple read-only list tool with one well-documented parameter, an output schema, and safety-relevant annotations, the description is fully sufficient. It covers what the tool returns, what it does not return, the relevant alternative, and the campaign targeting behavior, leaving no important gap for an agent to guess at.

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

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

Schema coverage is 100%, and the schema already documents campaignId thoroughly, including its default value and how to use an id from growsurf_create_campaign. The description mostly restates this targeting behavior ('Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID'), adding no new parameter semantics beyond the schema.

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

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

The description uses a specific verb and resource — 'List your GrowSurf program's configured rewards' — making the operation unambiguous. It also draws an explicit distinction from participant rewards ('does not establish that a participant earned or received a reward'), which separates it from growsurf_get_participant without needing to inspect that tool.

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

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

The description explicitly states when this tool is not the right choice: to see whether a participant earned a reward, you should use growsurf_get_participant instead. It also clarifies the targeting behavior with campaignId and the fallback to GROWSURF_CAMPAIGN_ID, giving an agent clear conditions for invocation.

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 state readOnlyHint true, idempotentHint true, and destructiveHint false, so the safety profile is covered. The description adds valuable behavioral context beyond those annotations: 'Deleted programs are not returned' clarifies output filtering, and 'Does NOT require GROWSURF_CAMPAIGN_ID' clarifies an operational constraint. This is meaningful extra transparency for a zero-parameter 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 three sentences and every sentence earns its place: the first states the core function, the second gives when-to-use guidance, and the third adds behavioral filter and environment-variable context. It is front-loaded with the purpose and contains zero filler. This is an appropriately sized description 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?

The tool is a zero-parameter read-only list operation, and the output schema exists, so the description needn't enumerate the return fields. The description covers scope ('available to the bound team'), usage order (first before campaign-scoped tools), output filter (deleted programs omitted), and an important environment variable exception. Combined with annotations, nothing an agent needs to call it correctly is missing.

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

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

There are zero parameters, and the input schema is an empty object with 100% schema description coverage, so the baseline is 4. The description adds relevant context about the missing GROWSURF_CAMPAIGN_ID requirement, which helps an agent understand that no campaign ID is needed here unlike its siblings. This is a useful addition even though there are no explicit parameters to document.

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 by clearly stating what the tool does: 'List the GrowSurf programs available to the bound team.' This is a specific verb plus resource and scope. It also distinguishes itself from the many campaign-scoped sibling tools by positioning this as the entry point for choosing a campaign ID, so an agent can tell it apart from tools like growsurf_get_campaign or growsurf_list_campaign_rewards.

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

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

The description gives explicit usage guidance: 'Use this first when you need to choose a campaignId before calling campaign-scoped tools.' It also notes that GROWSURF_CAMPAIGN_ID is not required. It doesn't name a specific alternative tool or provide an explicit when-not, but the 'use first' instruction and the distinction from campaign-scoped tools clearly places it as the initial discovery step.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds meaningful behavioral disclosure by stating that webhook secrets are never returned, which is important security context an agent needs. The fallback targeting behavior is also clearly explained beyond the annotations.

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

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

Two short sentences with no filler. The core action is stated first, the important security caveat follows, and the parameter targeting rule is clearly front-loaded. Every sentence earns its place.

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

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

For a simple read-only listing tool with zero required parameters and an output schema, this description is complete. It covers the resource, the security caveat, and the parameter targeting behavior. The annotations carry the safety profile, and the output schema covers return values.

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 campaignId parameter is already well documented in the input schema. The description mostly restates the parameter's default behavior, so it adds little semantic value beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description names the exact resource and action: 'List your GrowSurf program's webhooks'. This clearly differentiates it from sibling tools like growsurf_list_campaigns and growsurf_list_integrations. The qualifier about secrets not being returned further sharpens what this tool specifically provides.

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

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

The description clearly states when the campaignId parameter is targeted and when the default GROWSURF_CAMPAIGN_ID is used. It gives enough context for the agent to know how the tool selects its scope, though it does not explicitly discuss alternatives or 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, and destructiveHint, but the description adds meaningful behavioral context: it explicitly says the call is read-only, explains the autoDisabled state (credentials stored but nothing delivered until reconnect), and notes that inapplicable integrations are omitted. This exceeds what the annotations alone convey and contains no contradictions.

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

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

The description is long but every sentence earns its place: it names example integrations, defines each state field, explains omission behavior, clarifies read-only semantics with a sibling pointer, and specifies the parameter default. The core action is front-loaded, and 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 documentation is already covered. The description adds everything else an agent needs: field semantics, omitted integration behavior, the dashboard-only connect path, the connect-link sibling, and the campaignId targeting rule. Nothing essential is missing for correct invocation.

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

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

The schema already documents campaignId fully, including its default to GROWSURF_CAMPAIGN_ID and the use case of passing a newly created campaign id. The description restates 'Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID,' adding no new meaning beyond the schema. With 100% schema coverage, the baseline of 3 applies.

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

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

The description opens with a specific verb and resource — 'List every integration your GrowSurf program can connect' — and defines the tool's scope and output fields (connected, enabled, autoDisabled, connectUrl). It also differentiates itself from the sibling growsurf_get_integration_connect_link by stating that connecting happens in the dashboard and routing users to that sibling for the connect link.

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

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

The description gives a concrete use case ('so you can check whether an integration is connected before you act on it'), states when not to use the tool ('connecting an integration happens in the GrowSurf dashboard, not through the API'), and explicitly names the alternative growsurf_get_integration_connect_link. It also clarifies the campaignId default behavior, giving an agent full routing context.

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