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

Annotations are all false, so the description carries the burden. It discloses idempotent behavior ('Existing participants are returned unchanged'), explains affiliate status logic in detail, and warns about misuse. It doesn't mention side effects like email triggers, but the core behavior is well covered.

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 lengthy but each sentence carries essential information. It front-loads the primary action, then details conditional logic. No filler, and the structure follows a logical order from purpose to exclusions to parameter behavior.

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 enrollment logic, campaign targeting, and warnings. It omits explanation of several less-critical parameters and does not describe output or error scenarios, though the output schema covers return values. Adequate but with gaps.

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

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

Schema coverage is only 18%, so description must compensate. It does explain isAffiliate and referredBy extensively, and reinforces campaignId. However, it is silent on other parameters like metadata, ipAddress, fingerprint, etc., leaving those unclear. It adds value for the most critical params but not all.

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 'Add or fetch a participant by email' with a specific verb and resource, and clarifies that existing participants are returned unchanged. It also contrasts with public application flows, distinguishing itself from the broader enrollment context, though it does not explicitly name a sibling 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?

It provides explicit guidance: 'This is trusted direct enrollment; do not use it for a public application when the program requires affiliate review.' It also details when to set isAffiliate true/false and the interaction with referredBy, plus campaign targeting via campaignId or default. While it doesn't name an alternative tool, the conditions are clear.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description's burden is reduced. It adds value by specifying the output nature (eval prompts and acceptance checks for four areas), which goes beyond the structured hints and aligns with the read-only intent 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?

A single, well-structured sentence that front-loads the primary action and then lists specific sub-areas. It is concise, and every phrase contributes to understanding the tool's scope without unnecessary 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?

The tool has two optional parameters and an output schema, but the description does not explain parameter usage, which is critical for correct invocation. While the output schema likely documents returns, the input side is underspecified, leaving the agent uncertain about how to set programType or includeOneShotPrompts for different eval scenarios.

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 0% and the description does not mention either parameter (programType or includeOneShotPrompts). The agent receives no semantic guidance on how these optional parameters influence the generated prompts, forcing inference from enum values and defaults alone.

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

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

The description clearly states the tool generates one-shot eval prompts and acceptance checks for GrowSurf program creation, listing specific coverage areas (starter content review, conservative rewards, configuration review, frontend install proof). This distinguishes it from sibling CRUD tools and leaves no ambiguity about its function.

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

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

The description mentions 'for agent steering' but does not explicitly state when to use this tool versus alternatives or provide exclusions. Since no sibling performs a similar function, the intended use is somewhat self-evident, but the lack of explicit usage context or conditions is a gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it generates snippets for specific languages and includes a particular workflow, which is useful but not deeply behavioral. It does not disclose rate limits, response format, or any side effects beyond what annotations imply. 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 a single, dense sentence with no filler. It front-loads the core action and includes relevant details about languages and a key workflow. It could be slightly more structured (e.g., listing all workflows), but it is appropriately concise and information-dense.

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 6 optional parameters, two enums, and an output schema, this description is far too minimal. It does not explain how the parameters customize the generated snippets, what the response contains, or any workflow-specific requirements. Even though annotations cover safety, an agent would not know how to correctly populate the parameters to get the desired snippet. The description leaves too much implicit.

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

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

Schema description coverage is 0%, so the description must explain the parameters. It only hints at the 'language' parameter by listing languages and the 'workflow' parameter by mentioning 'Create Mobile Participant Token' (which maps to one enum value). There is no explanation of email, campaignId, referredBy, or participantIdOrEmail, leaving most parameters under-explained. The description carries the burden but only partially addresses 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 clearly states the action ('Generate') and the output ('official REST API library snippets') for a specific set of languages. It also highlights a distinct workflow ('Create Mobile Participant Token'), making the purpose clear. However, it does not explicitly distinguish this tool from related snippet-generation siblings like growsurf_client_snippets or growsurf_embeddable_element_snippet, so it loses a point for not differentiating.

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 the many sibling tools. No conditions, prerequisites, or alternatives are mentioned. The description only states what it does, not when it should be chosen over other snippet generators or integration guides. This is a significant gap for a tool with many related 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 already indicate destructiveHint=true and idempotentHint=true, but the description goes far beyond by detailing exactly what is destroyed (referrals, rewards, commissions, payouts), the response structure (summary and per-row statuses), and the fact that a 200 response can include NOT_FOUND or ERROR rows. This prepares the agent for partial failures and cascading effects, adding significant value beyond structured metadata.

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 yet efficient — the destructive warning is front-loaded, and every subsequent sentence adds distinct value (chunking, response format, campaign fallback). There is no filler or redundancy, and the structure guides the agent from warning to usage to expectation.

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 this complexity — bulk deletion with nuanced response semantics and destructive side effects — the description is complete. It explains limits, response parsing, status meanings, and the campaign fallback, all essential for correct invocation, especially given the existing 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?

The input schema provides 100% description coverage for both parameters, including mixed types, max 200 entries, and the default campaignId. The description reiterates these points but does not introduce new semantic meaning beyond the schema, so it meets the baseline for high schema coverage without adding extra value.

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 bulk deletes participants from a GrowSurf program, using the specific verb 'delete' and resource 'participants'. It distinguishes itself from single-participant and campaign-level tools by emphasizing 'bulk' and 'in one request'. The scope is immediately evident.

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 offers practical usage guidance, including chunking lists larger than 200 entries and the campaignId default behavior. However, it does not explicitly name alternative tools (e.g., growsurf_update_participant) or state when not to use this tool, so it's clear but lacks comparative 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 destructiveHint=true and idempotentHint=true. The description adds the 'before delay elapses' limit and the return shape, but does not disclose error behavior (e.g., if the delay already elapsed or the participant is not found). It provides some context beyond annotations but not comprehensive.

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 well-structured sentences: the first states the action and context, the second covers return format and campaignId default. It is efficient and avoids fluff, though the return format might be redundant given an output schema exists.

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

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

The description covers the core purpose and typical scenario, but misses edge cases like behavior after the delay elapses, error messages, and which participant identifier to prefer. With an output schema present, it is adequate for a simple cancel operation but not fully complete.

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

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

Schema description coverage is only 33% – only campaignId is described. The description clarifies campaignId's default but leaves participantId and participantEmail entirely undocumented. With low coverage, the description should compensate but does not, leaving param semantics weak.

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 action ('cancel'), the resource ('a pending delayed referral trigger for a participant'), and the timing condition ('before the delay elapses'). This distinguishes it from sibling tools like growsurf_trigger_referral, making the purpose unambiguous.

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

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

It gives a specific use case ('on refund/cancellation') and implies the constraint that cancellation is only valid before the delay expires. However, it does not explicitly compare with alternatives or state when not to use it, leaving the agent to infer routing logic.

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 provide no safety hints (all false), so the description must carry the transparency burden. It discloses that URLs are short-lived, that the tool targets campaignId or falls back to GROWSURF_CAMPAIGN_ID, that it does not prove installed sites, and that it rejects arbitrary inputs. This is meaningful behavioral disclosure. A minor gap is that it doesn't mention any side effects (e.g., whether it stores or modifies anything), but given the read-like nature, this is acceptable.

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, front-loaded with the core action, then constraints and targeting. It avoids filler but does repeat 'screenshot' a few times. Overall it is efficient and well-structured for an agent to parse quickly.

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

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

Given an output schema exists (which will define the return structure), the description covers everything an agent needs to decide when to use it and how to invoke it: the exact trigger, the limitation (does not prove installation), the rejection of arbitrary inputs, and the default behavior for the campaignId parameter. 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?

The single parameter `campaignId` is fully documented in the schema with 100% coverage, and the description only restates the same information ('Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID'). Since the schema already covers the semantics, the description adds no new meaning, so the baseline of 3 applies.

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

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

The description clearly states the action: 'Capture temporary GrowSurf preview screenshots'—a specific verb with a specific resource. It also explicitly scopes the tool to the controlled referrer window and referred-friend experience, and disambiguates from any generic screenshot tool by stating it does not accept arbitrary URLs or external targets. This strongly distinguishes it from the listed sibling tools, none of which are screenshot-specific.

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?

Contains an explicit trigger condition: 'after the user explicitly asks for screenshots or screenshot proof.' It also names an alternative ('use browser automation for that') to clarify what this tool does not prove, and clearly states what it does not accept (arbitrary URLs, HTML, JavaScript, external targets). This leaves no doubt about when to use this tool versus alternatives.

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

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

Annotations already disclose that the tool is read-only and idempotent (readOnlyHint=true, idempotentHint=true). The description adds minimal behavioral context by noting it produces 'copy-pasteable' snippets and includes 'placement guidance', but it does not elaborate on output specifics or side effects. Given the annotations cover safety, the description provides only marginal additional transparency, warranting a mid-range score.

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 efficiently communicates the tool's purpose and scope, front-loading the action and resource. It avoids fluff but is slightly dense; however, it remains concise and clear. No redundant information is included, though it could be broken into two sentences for better readability.

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 (all optional) and no schema parameter descriptions, and an output schema exists but its content is not provided. The high-level description contributes little to understanding the parameter functionality or the expected return structure. Without any explanation of how parameters control the output, the context is incomplete for an agent to use it effectively.

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% – none of the 8 parameters have descriptions in the schema. The tool description does not explain any parameter such as `programType`, `singlePageApp`, `referralTrigger`, or the boolean toggles. With zero compensation for the missing schema documentation, an agent cannot determine how these parameters affect the generated snippets. This is a 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?

The description states a clear verb ('Generate') and a specific resource ('copy-pasteable client-side snippets for GrowSurf referral tracking, embeddable elements, and the GrowSurf Window (JS + CSS)') with placement guidance. It names the types of snippets and distinguishes itself from pure configuration tools, though it does not explicitly differentiate from the sibling `growsurf_embeddable_element_snippet` which overlaps in scope.

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

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

The description offers no explicit guidance on when to use this tool versus alternatives. It mentions 'placement guidance for app UI work' which implies a UI integration scenario, but it does not state exclusions or name sibling tools (e.g., `growsurf_embeddable_element_snippet`) that cover specialized cases. An agent would have to infer usage, which is not sufficient.

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

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

Beyond the annotations (mutation, non-destructive), the description adds key behaviors: integrations/credentials are not copied, active rewards are copied, and the resulting program is a DRAFT. This informs the agent of the tool's side effects and scope, which is valuable.

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

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

Two sentences, front-loaded with the primary action and outcome, then caveats about exclusions and defaults. Every sentence adds information; no wasted words or repetitive phrasing.

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 the tool's purpose, parameter default, and critical behavioral nuances (what is not copied). The presence of an output schema reduces the need to describe return values. It does not mention edge cases or side effects on the original, but for a clone operation this is sufficient.

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

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

The schema already fully documents the campaignId parameter, including its default behavior and how to obtain it. The description merely restates this ('Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID') without adding new meaning. With 100% schema coverage, a baseline 3 is appropriate.

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

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

The description clearly states the action ('Clone'), the resource ('GrowSurf program (campaign)'), and the outcome (a new DRAFT program). It also details what is and isn't copied, making it distinct from sibling tools like create_campaign or update_campaign by focusing on duplication.

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 (duplicating an existing program) but does not explicitly contrast with alternatives or state when NOT to use it. It avoids mentioning that this is for cloning rather than creating from scratch, leaving the agent to infer from the verb 'clone'.

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

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

Annotations only set readOnlyHint=false and destructiveHint=true. The description goes far beyond, disclosing trial period, key locking until email verification, auto-deletion after 7 days, key replacement on first sign-in, and the specific error codes. This is extensive behavioral context that an agent needs and is not present in 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 long but every sentence adds necessary information about verification, error handling, and key storage. It is front-loaded with the primary purpose and preconditions. While dense, it is not redundant; a 4 is appropriate for its efficiency given the complexity.

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 account-creation tool, the description covers the full lifecycle: prerequisites, token retrieval, verification, error codes, retry logic, key replacement, and automatic deletion. An output schema exists so return values need not be explained. Nothing essential for correct invocation 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 0%, so the description carries the full burden. It explains constraints on email (personal/disposable not accepted) but does not clarify the meaning or format of company, firstName, or lastName. Partial compensation; enough to avoid misuse of email but leaves other fields ambiguous.

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 (create a brand-new account), the resource (GrowSurf account), and the key outcome (returns an API key). It also differentiates from all siblings by noting it's the only tool not requiring GROWSURF_API_KEY. This is unambiguous and distinguishes it well.

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

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

Provides explicit conditions for use (owner approval, terms acceptance) and explicitly names an alternative (hosted MCP server) when key storage is not possible. Also gives post-call guidance (verification email, resend tool) and when to retry. This fully covers when and when-not to use.

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

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

The annotations are all false, so the description carries the full burden of disclosing effects. It does this well: the program is created in DRAFT status, owned by the bound team, starts with GrowSurf's starter rewards switched off, custom currency is immutable after creation, and no GROWSURF_CAMPAIGN_ID is required. It also says the response includes the new program id and how to use it, which is exactly the operational behavior an agent needs.

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 the MCP norm, but nearly every sentence earns its place by preventing a common mistake: leaving rewards to renting behavior, passing too much bulk because currency immutable, or expecting it is a patch tool. It is front-loaded with the core purpose and only later moves to workflow details. It does not have any fluff, but a bullet or paragraph break could help an agent scan it quickly, so it loses one point on structure.

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

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

For a creation tool, the description gives all the context needed to invoke it correctly: defaults, required vs optional behavior, what is not accepted, what the response supplies, and how to chain the id into the rest of the GrowSurf toolset. Since an output schema exists, the description does not need to inventory the return fields. There are no major gaps that would cause a placeholder execution besides unclear user-provided values, which no static text can resolve.

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 parameter-based schema coverage only 29%, guidance needed to compensate, and the description does that for the most important fields: `type` is mandatory, `goal` is set only at creation and configures sharing, `currencyISO` defaults to USD and is immutable, and `rewards` has clear inclusion rules plus the `[]` distinction. `name`, `companyName`, and `companyLogoImageUrl` are left to their self-evident names and simple schema labels, so the description does not document every param but it does add high-value semantics for the ones that matter most.

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

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

The description opens with a specific verb and resource: 'Create a new GrowSurf program (campaign)' and immediately states the main behavior—pre-populating the program with starter content and optionally adding rewards. It also distinguishes this creation tool from related configuration tools by explicitly saying editor-tab config is not accepted here and that the resulting id is used by other tools.

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

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

The description gives clear guidance on when valid, including 'Only type is required', when to omit or send rewards, and why to pass goal. It states that editor-tab configuration is not handled here and should be fetched and patched afterward. It does not explicitly name sibling alternatives like growsurf_create_campaign_reward or growsurf_update_campaign_design, but it points the agent to the correct post-creation workflow using config sub-resources, so the guidance is strong but not fully explicit on alternative tool names.

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 write operation (readOnlyHint=false). The description adds the behavioral constraint that type must match program type for the server to accept it, and explains the campaignId fallback. It does not disclose side effects or edge cases, but for a create operation the key behaviors are covered.

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 with a clear purpose: the action, the most important validation rule, and the campaign targeting behavior. No fluff 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?

Given a complex 23-parameter schema, the description is too terse to fully guide an agent. It covers the essential 'what' and 'where' but doesn't explain reward types, required fields beyond 'type', or how this fits into the broader campaign creation flow. The output schema is available, so return values are covered, but an agent would still need to deeply inspect the schema to use this tool correctly.

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

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

Schema description coverage is only 22%, and the description compensates only minimally. It adds the type compatibility rule for the 'type' parameter and restates the campaignId default which the schema already documents. The remaining 18+ parameters are left unexplained in both the schema and the description, so the agent has little guidance on what to fill.

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

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

States a specific verb and resource: 'Create a new campaign reward (reward config)'. It clearly distinguishes from sibling update/list/delete tools by the word 'Create' and identifies the object being created.

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

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

Provides clear context on when to use this tool: it mentions the type compatibility rule and the campaignId default behavior. Although it doesn't explicitly say 'use this instead of update_campaign_reward', the verb 'create' and sibling names make the distinction 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 description discloses important behaviors beyond the sparse annotations: secret is write-only and never returned, and campaignId defaults to GROWSURF_CAMPAIGN_ID when omitted. This provides useful context for invocation and security. It does not contradict annotations and adds meaningful insight.

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

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

The description is concise (three sentences) and front-loaded with the primary purpose. Each sentence adds value without redundancy, covering the essential parameter behaviors and default behavior in a compact, well-structured manner.

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 create-webhook tool, the description covers the required payloadUrl, events subscription semantics, secret signing behavior, and campaign targeting. It omits details about isEnabled and potential error conditions, but given the output schema exists and annotations carry little weight, it is sufficiently complete for an agent to call correctly.

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

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

Schema coverage is only 40%, but the description compensates by explaining payloadUrl is required, events list semantics (omit to subscribe to none), and secret's write-only nature. It also confirms campaignId default. The only parameter not mentioned is isEnabled, which remains bare, but the majority of parameters are clarified.

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 action ('Add a webhook') and the resource ('to your GrowSurf program'). It distinguishes from siblings by the verb 'add' (create) versus update/delete/list, but does not explicitly name alternatives. The purpose is unambiguous, though not explicitly differentiated.

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 parameter usage details, such as payloadUrl being required and events semantics, but gives no explicit guidance on when to use this tool versus siblings like growsurf_update_campaign_webhook or growsurf_delete_campaign_webhook. The intended use case is implied by the create nature, but not explicitly stated.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds context about 'trusted direct enrollment' and the risk of misuse for public apps. However, it does not disclose detailed side effects, permissions, or rate limits, so only partial transparency 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 concise sentences that front-load the main action, then add a crucial warning and targeting logic. Every sentence earns its place, no 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 tool with 11 parameters and an output schema, the description leaves many parameters unexplained (email, lastName, metadata, etc.). It does not mention how token creation interacts with the output or whether any preconditions exist. The warning about affiliate review is useful but the overall context is incomplete.

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 needs to compensate. It adds meaning for campaignId (default behavior) and isAffiliate (trusted enrollment context), but does not explain the other 9 parameters (email, firstName, etc.). It adds some value but not sufficient for the low 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?

The description clearly states the verb and resource: 'Create or fetch a participant, then create a participant-scoped mobile SDK token.' It distinguishes itself from siblings by mentioning the token scope and the GrowSurf REST endpoint, and notes the campaign targeting behavior. No confusion about what it does.

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 a clear warning: do not use for public application when affiliate review is required, which helps decide when to avoid it. It also implies when to use it (trusted direct enrollment). It does not explicitly name alternative tools, but the warning and context are helpful.

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 signal mutation and non-idempotency, and the description adds non-obvious behavior: draft-by-default unless isPublished is set, campaignId fallback to GROWSURF_CAMPAIGN_ID, and the 10MB FILE upload path. It does not discuss duplicate/retry behavior, but it goes meaningfully beyond what annotations alone convey.

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

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

The description is front-loaded with the operation and resource discriminators, and every clause maps to a real parameter or workflow step. It is compact despite covering a conditional multi-type API.

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 conditional create operation, the description integrates the multi-step upload flow, field constraints, defaults, and targeting behavior. Return-value details are handled by the output schema, so an agent has enough to invoke the tool correctly.

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

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

With only 50% schema coverage, the description compensates for the most important conditional parameters: url for LINK, text for TEXT, uploadTicket/uploadResult for FILE, isPublished defaulting, and campaignId fallback. It leaves title/category/description mostly implicit, but the schema names those self-evidently and the critical disambiguation is covered.

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

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

The description names a specific action—creating a participant-facing program resource—and enumerates the exact resource types (FILE, LINK, TEXT). It also names the prerequisite sibling workflow for FILE, which differentiates it from update/delete/prepare tools.

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

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

It clearly tells FILE callers to call growsurf_prepare_program_resource_file first and pass the returned values unchanged, and it states the LINK and TEXT field requirements. It does not explicitly contrast with update/list/delete siblings, but the create-vs-manage distinction is clear enough from the verb and context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description goes beyond by specifying exactly what gets destroyed (reward config and connected upfront-discount coupons) and the return shape ({ id, success }). This aligns with annotations and adds valuable context about the cleanup behavior. It does not contradict any annotation.

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 with zero filler. The core action is front-loaded, and each sentence earns its place: action/effects, parameter clarification, and targeting logic. No redundancy or verbosity.

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 with an output schema, the description covers the return shape, the cleanup side effects, and the default target behavior. It does not mention error conditions or permissions, but annotations provide the destructive hint and the output schema presumably documents the response. Overall, it is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 50% (only campaignId has a description). The description compensates: it explicitly identifies '`campaignRewardId` is the reward key' and explains the default behavior of campaignId (targets GROWSURF_CAMPAIGN_ID when omitted). This adds meaning beyond the bare schema for the required parameter and clarifies optional parameter semantics.

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

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

The description clearly states the verb ('Delete'), the resource ('campaign reward'), and the scope ('from your GrowSurf program'). It also details the side effects (deactivated, removed, coupons cleaned up), which distinguishes it from update or create siblings. An agent can immediately tell what this tool does.

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

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

The description makes it clear that this is the delete/removal tool, implying use when a reward should be permanently removed. However, it does not explicitly contrast with update_campaign_reward for partial modifications or state when not to use it. The context is clear but could be stronger with an explicit 'use this for deletion, use update for changes' statement.

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

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

Annotations declare destructiveHint=true, so the destructive nature is already disclosed. The description adds value by specifying the return format ({ id, success }) and the fallback targeting behavior (GROWSURF_CAMPAIGN_ID when campaignId is omitted). It does not contradict any annotations and provides useful behavioral context beyond the schema.

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

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

The description is remarkably concise: two sentences plus a targeting note. It fronts the core action immediately, includes only essential behavioral details, and contains no filler or redundant phrases. 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 delete operation with annotations covering destructive behavior, the description provides the return format and the campaign resolution logic, which are critical for correct invocation. It does not mention side effects or prerequisites, but given the simplicity of the operation and presence of an output schema, the description is sufficiently complete. A slight gap is not explaining the exact format of webhookId (e.g., where to obtain it), but this is minor.

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

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

The schema covers campaignId with a detailed description, while webhookId has no schema description. The tool description mentions 'by id' for webhookId but adds no new meaning—webhookId's role is inferred from the name. For campaignId, the description restates what the schema already says ('Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID') without adding further detail. With 50% schema coverage, the description only partially compensates for the undocumented webhookId.

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 action ('Remove'), the resource ('a webhook'), and the scope ('from your GrowSurf program'), which distinguishes it from sibling tools like create, update, list, and test webhooks. The inclusion of the return format { id, success } adds clarity 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 implies the use case (deleting a webhook) but does not explicitly provide when-to-use guidance or mention alternatives. It does not state when not to use this tool or contrast it with other webhook operations. The targeting logic for campaignId is a parameter detail, not usage guidance. Overall, usage context is clear from the name but not explicitly articulated.

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 destructiveHint=true and idempotentHint=true, and the description adds the important nuance that the Media Center asset survives deletion. It also discloses the campaignId targeting behavior, going beyond the minimal mutation signal.

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

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

Two concise sentences front-load the action, then clarify the asset side effect and campaign targeting. Every sentence adds information; 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 2-parameter destructive tool with an output schema and annotations, the description covers the key call-time decisions: what is deleted, what is not deleted, and which campaignId is used. It doesn't discuss reversibility, but destructiveHint and the delete verb already convey that risk.

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?

resourceId is not described in the schema and the description only identifies it by the noun 'participant resource.' The campaignId fallback behavior is repeated from the schema, so the description adds modest but not comprehensive parameter meaning for 50% 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?

States a specific action and object: 'Delete a participant resource from your GrowSurf program.' It also distinguishes the tool's effect from deleting a 'reusable Media Center asset,' and the target object differs from siblings like update_program_resource or delete_campaign_webhook.

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

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

Provides clear context by noting that the reusable Media Center asset is not removed, which helps an agent avoid using this tool when asset deletion is intended. The campaignId fallback/override behavior also explains when to pass the optional parameter, though no alternative tool is named.

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

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

The description discloses critical behaviors: automatic compliance handling (company name, postal address, unsubscribe link), suppression of unsubscribed participants, and the 400 error until verification is complete. While annotations indicate destructiveHint=true and readOnlyHint=false, the description adds concrete details about side effects and preconditions, going 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?

The description is appropriately long given the tool's complexity, with the core purpose and options front-loaded, followed by prerequisites and behavior. It is well-structured and each sentence contributes essential information, though it is denser than a minimal description.

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

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

The description fully covers selection between template and free-form, identification methods, targeting, prerequisites, and failure behavior. An output schema exists, so return details are not required. It is complete for an agent to call this tool correctly without additional guidance.

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 schema coverage at 57%, the description compensates by explaining the either/or relationship between emailType and subject/body, the default behavior for campaignId, and the meaning of participant identification via ID or email. It adds operational meaning beyond the schema's basic property 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 states a specific action ('Send an email to a participant'), identifies the resource (participant by ID or email), and differentiates between template and free-form email modes. It is unambiguous and does not merely restate the tool name, and it clearly distinguishes the tool's function from other GrowSurf tools by focusing on email delivery.

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 use: either emailType (template) or subject+body (free-form), and outlines prerequisites (team verified, custom email domain verified) and default targeting via campaignId. It does not explicitly name alternative tools, but the tool's specific function (sending participant emails) makes usage context clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds no behavioral detail beyond 'generate', offering no information on side effects, rate limits, authentication needs, or what the snippet actually produces. It essentially restates the name with a minor addition.

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, clear sentence with no extraneous words. The core purpose is stated upfront, and the optional modifier is concise. It is an efficient, well-structured definition.

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

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

Given the tool has 3 parameters (one required) with a nested object and an output schema exists, the description is minimal. It conveys the basic intent but does not explain the role of all parameters or when to use it. Since the output schema is present, return details are covered elsewhere, but the description lacks depth for a tool with this complexity.

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 touches on 'auth attributes' which maps to withAuthAttributes, but it does not explain the 'participant' object or how it relates to the element. The explanation is incomplete, leaving the agent to guess the purpose of participant fields like email and names.

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

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

The description states a specific verb ('Generate') and a precise resource ('HTML snippet for a GrowSurf embeddable element'), plus a clarifying modifier about optional auth attributes. This clearly distinguishes it from sibling snippet tools like growsurf_client_snippets or growsurf_grsf_config_snippet, which target different aspects of embedding.

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

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

No guidance is provided on when to use this tool versus alternatives such as growsurf_client_snippets or growsurf_api_library_snippets, nor any conditions or prerequisites. The description does not explain the context in which this snippet generator 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 establish read-only, idempotent, non-destructive behavior. The description adds a non-obvious semantic caveat about reward settings and clarifies target selection behavior, both of which help the agent interpret the response correctly 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 compact and front-loaded with its purpose, followed by a valuable caveat and a parameter-targeting note. It contains minimal filler, though the REST qualifier and default mention overlap with schema details.

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

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

For a single-parameter, read-only tool with full schema coverage and an output schema, the description covers the important traps: target selection and misinterpretation of reward settings. No critical information for correct invocation 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 campaignId schema entry already explains the default and how to use an id from growsurf_create_campaign. The description re-states the default behavior but does not add meaningful 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 clearly identifies the action ('Fetch') and resource ('campaign (program) details'), making the core purpose easy to grasp. It distinguishes from create/update/delete/list siblings, though it does not explicitly differentiate itself from the more specialized get_campaign_* sibling tools.

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

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

The description gives useful context: it is the campaign-level fetch and falls back to GROWSURF_CAMPAIGN_ID when campaignId is omitted. It also steers agents away from treating embedded reward settings as proof of earned rewards and points them to the participant record for that data.

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 valuable behavioral nuance: the observation window (7- or 30-day), the grouping keys by program type, and crucially the warning that 'unavailable history does not mean an action never happened'—directing the agent to read coverageStartAt/state/reason before interpreting nulls. This goes beyond annotations and is essential for correct interpretation.

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

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

The description is dense but well-organized. It front-loads the primary purpose, then moves through grouping, stages, observation window, cohort bounds, and interpretation guidance. Every sentence contributes functional information; there is no fluff. While it is longer than average, the complexity of the tool justifies the length, and the logical flow makes it scannable.

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

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

For a tool with 6 parameters, 2 enums, and an output schema, the description is exceptionally complete. It covers the exact stages, the cohort selection logic, the observation window options, the default target, and vital data-interpretation warnings. Since an output schema exists, return-value details are not required in the description. Nothing necessary for an agent to invoke this tool correctly and interpret results 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 100% schema coverage, each parameter is already documented. The description adds meaningful semantics beyond the schema: it ties cohortFrom/cohortTo together via the conditional requirement, explains that omitting them yields the latest matured cohort, and clarifies the default behavior of campaignId (targets GROWSURF_CAMPAIGN_ID when omitted). This helps the agent reason about parameter combinations and defaults, exceeding the baseline for high 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?

The description opens with a specific verb and resource: 'Fetch strict activation for eligible participants in one enrollment cohort.' It distinguishes this from general campaign analytics by specifying 'strict activation' and the enrollment cohort scope, and it immediately clarifies the two grouping modes (referral vs. affiliate). This makes the tool's unique purpose unambiguous and separates it from sibling analytics tools.

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

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

The description provides clear context for when to use this tool: it is specifically for activation analytics in a single enrollment cohort, with explicit instructions on cohort bounding ('Omit both cohort bounds for the latest fully matured cohort') and interpretation ('Read coverageStartAt, state, and reason...'). While it doesn't explicitly name alternative tools to avoid, the detailed policy on cohort handling and the warning about missing history effectively guide correct usage without needing exclusions.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context beyond that: the default timeframe of 365 days and max of 1825, the campaignId fallback to GROWSURF_CAMPAIGN_ID, that timezone/platform apply only to engagement, and that engagement's coverageStartAt/state/reason distinguish measured zeroes from partial or unavailable history. 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?

Every sentence earns its place: purpose first, then the troubleshooting pointer, then parameter and scoping guidance. The description is dense but not padded, with no redundant restatement of the schema.

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

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

Given 8 parameters, 2 enums, and an output schema, the description covers defaults, exclusions, engagement semantics, timeframe scoping, and the target fallback. With an output schema present, omitting return-value details is fine. There is no missing guidance an agent needs to call this tool correctly.

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

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

Schema coverage is 88%, but the description adds meaning the schema lacks: interval day/week/month yields a per-period 'series', include is comma-separated and names the exact options, engagement is defined as grouping unique active/sharing/repeat/retained participants by portal views and share actions, and engagement's coverage fields carry semantics. It also clarifies days vs startDate/endDate usage and timezone/platform scope.

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 first sentence names a specific verb and resource ('Fetch analytics for your GrowSurf program') and enumerates the concrete metrics: participants, referrals, impressions, per-channel shares, and affiliate revenue/commission/payout. This is enough to distinguish it from other analytics siblings like growsurf_get_campaign_activation_analytics and growsurf_get_participant_analytics, even without comparing schemas.

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

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

Explicitly routes the agent to a sibling for metric definitions or count reconciliation: 'call growsurf_troubleshoot_referral_tracking with symptom numbers_do_not_match rather than guessing.' It also gives concrete usage conditions for interval, include, engagement, and timeframe parameters, so an agent knows exactly how to shape the request.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only nature is covered. The description goes beyond this by detailing default behavior for participantAvatarStyle (unknown values default to INITIALS), handling of null and omitted fields (null returned as null, omitted and null use localized defaults), omission of confirmation section when no fields stored, and the fallback to GROWSURF_CAMPAIGN_ID. These behavioral specifics add significant value beyond annotations.

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

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

The description is dense but every sentence earns its place. It front-loads the purpose, then lists fields, then explains default and edge-case behaviors. There is no redundancy, filler, or repetition; it packs substantial information into a well-organized paragraph without wasted words.

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

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

Given the output schema exists, return values are fully documented elsewhere. The description covers all non-obvious behaviors: field list, enum values, defaults, null handling, and campaign targeting. It also clarifies the confirmation section omission. An agent has everything needed to call this tool correctly without consulting additional documentation.

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 for the single parameter campaignId is 100%, with the schema description already explaining its default and purpose. The tool description repeats the targeting behavior but adds no new semantic detail. Per the rubric, when schema coverage is high, the baseline is 3, and the description adds little beyond that baseline.

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

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

The description clearly states the verb 'Fetch' and the resource 'configured design fields for your GrowSurf program', then enumerates the specific fields returned. This unambiguously distinguishes it from the sibling growsurf_update_campaign_design, so an agent can tell them apart without opening the schema.

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

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

The description makes the read intent clear but does not explicitly state when to use this tool versus alternatives like growsurf_update_campaign_design. There is no mention of exclusions or conditions for selection; the usage is implied by the 'Fetch' verb rather than stated as guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it returns the full object with all fields and current values, and it falls back to GROWSURF_CAMPAIGN_ID when campaignId is omitted.

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

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

Two sentences with no filler; the primary purpose is front-loaded, the return shape is clarified, and the default campaign behavior is stated compactly. 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 tool with one optional parameter, full schema coverage, strong annotations, and an output schema, the description covers everything needed to invoke it correctly. It explains the object shape, update relationship, and default campaign resolution, 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 description coverage is 100% and the campaignId property is already well documented in the schema, including its default and provenance from growsurf_create_campaign. The tool description repeats the default behavior but adds little beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb ('Fetch') and resource ('Emails tab configuration'), including what that resource contains (participant and admin email templates and settings). It clearly distinguishes this read operation from the sibling update_campaign_emails 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 makes clear this is a fetch operation and that the returned shape is what you send back on update, implicitly connecting it to growsurf_update_campaign_emails. It also explains campaign targeting behavior with the default GROWSURF_CAMPAIGN_ID, giving an agent actionable context, though it doesn't explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's safety profile is well covered. The description adds the behavioral fact that it returns the full object with every field, which is useful for understanding the response but not a new risk or constraint. It adds minor context beyond annotations without contradicting them.

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

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

The description is concise at three sentences with no redundancy. The purpose is front-loaded, the return shape is clearly stated, and the parameter default is mentioned efficiently. Every sentence contributes essential information, and there is no fluff 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?

For a simple read-only getter with one optional parameter and an existing output schema, the description is complete. It states what the tool fetches, the default behavior, and the return shape. While it could mention that the Installation tab is a sub-configuration of a campaign or that this is typically used before updating, those are minor and covered by the output schema and sibling 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?

The schema provides 100% coverage for the single parameter campaignId, including its default behavior and a recommendation to pass the id from growsurf_create_campaign. The description repeats this in its last sentence without adding new meaning. Since schema coverage is high, the baseline of 3 applies; the description does not enhance parameter understanding beyond the schema.

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

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

The description clearly identifies the tool's purpose: it fetches the Installation tab configuration for a GrowSurf program. The verb 'Fetch' and the specific resource 'Installation tab configuration' make it unambiguous. It also distinguishes it from sibling getters like get_campaign_design or get_campaign_options by naming the exact tab and mentioning the return shape (full object same as 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 mentions the default campaignId behavior and that the returned object is the same shape sent on update, which subtly implies a read-before-update workflow. However, it does not explicitly state when to use this tool versus alternatives like update_campaign_installation or other getters. No exclusions or alternative tools are named, leaving usage context implicit.

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

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

Annotations readOnlyHint=true, idempotentHint=true, destructiveHint=false already tell the agent this is a safe read operation. The description adds behavioral nuance by noting the `autoFulfillRewards: false` does NOT prove rewards went undelivered (a corrective against misinterpretation), and clarifies that passing `campaignId` is optional with a default. This goes beyond the annotations without contradicting them.

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 packs essential details into a few sentences: what is fetched, the return shape, the autoFulfillRewards caveat, and the targeting default. It is front-loaded with the purpose, and every sentence adds value. No fluff 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?

Given the low complexity (1 optional param), high schema coverage, and presence of an output schema, the description is quite complete. It mentions return shape ('same shape you send back on update') and cautions against misinterpreting a field. Missing only explicit indication of which specific fields exist, but the output schema covers that. Strong for the tool's complexity.

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% (the description for campaignId explains the default and how to get the id from create_campaign). The description itself does not add much beyond the schema, but it reinforces the default behavior architecturally which is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Fetch the Options tab configuration' and lists what is included (referral triggers, anti-fraud lists, notifications, etc.), which is specific and distinguishes it from related tools like update_campaign_options. However, it doesn't explicitly contrast with siblings that might also fetch campaign configuration (e.g., get_campaign_design, get_campaign_emails), though the listing of scope is enough to infer differentiation.

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

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

The description provides context on when to use it (fetch options) and explains the `campaignId` targeting behavior including the default to GROWSURF_CAMPAIGN_IDepth. It does not explicitly exclude alternatives or say when NOT to use it, but it is clear enough for an agent to know it's the right call for reading options. The caveat about autoFulfillRewards is more of a semantic clarification than usage guidance.

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

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

Even with readOnlyHint and idempotentHint already provided in annotations, the description adds valuable behavioral clarity: the program is checked before returning the link, the response reports connected/enabled/autoDisabled state, and a working link still comes back when programVerified is false. It also clearly states the product limitation that GrowSurf cannot link accounts on the user's behalf.

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

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

The description is front-loaded with the core purpose and every major sentence carries useful behavior or usage guidance. It is somewhat dense with examples and fallback behavior details, but nothing is filler. It could be slightly trimmed, especially around the examples, without losing 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 two-health-parameter, read-only, non-destructive tool with an output schema, this description is effectively complete. It covers the main use intent, exactly what to give the user, integration restrictions, program targeting, state reporting, and fallback behavior. An agent should not need to guess anything else before calling it.

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 describes both parameters at 100% coverage, so the baseline is 3. The description adds value beyond the schema by explaining how to use the returned URL in conversation, emphasizing that integration must match a supported key, and adding constraints like referral-program-only integrations and Wise being affiliate-only.

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 very specific verb and resource: 'Return a dashboard link that opens a specific integration's connect panel in the GrowSurf Program Editor.' It also gives concrete user-phrase examples and makes clear this is a link-returning tool, not a listing or mutation tool, so it is distinguishable from its siblings.

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

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

It explicitly says to use it 'whenever a user says they want to connect an integration' and gives real examples like 'connect Stripe' and 'set up PayPal or Wise payouts'. It also clarifies that GrowSurf cannot connect accounts on the user's behalf. However, it does not explicitly route to an adjacent sibling like growsurf_list_integrations or growsurf_integration_guide for neighboring cases, so it stops just short of full when/when-not alternative guidance.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds valuable interpretive context beyond that: referralStatus vs referralCount semantics, why zero referrals can align with CREDIT_AWARDED, and the distinction between fulfillment marking and actual delivery confirmation. This prevents misinterpretation of returned 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 core action is front-loaded, and the subsequent sentences each add necessary disambiguation about field meanings and campaign targeting. There is little to no filler, and the density is justified by the need to prevent interpretation errors.

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 that the annotations cover safety and the output schema describes return structure, the description supplies the missing decision info: how to find a participant ID, what the fields mean semantically, and how campaign targeting behaves. An agent has enough clarity to invoke this tool correctly without further investigation.

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

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

Schema coverage is only 33% since participantId and participantEmail lack descriptions, but the description compensates by explaining that either a GrowSurf participant ID or an email address is used to fetch the participant. It also gives campaignId practical meaning by noting the default GROWSURF_CAMPAIGN_ID behavior. Full field-level detail is still somewhat light, but the essential semantics are present.

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 opening phrase 'Fetch a single participant by GrowSurf participant ID or email address' states a specific verb, resource, and lookup method. It clearly distinguishes this tool from growsurf_list_participants by emphasizing 'single participant' and even names the sibling explicitly.

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

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

The description explicitly says 'Use growsurf_list_participants first if you need to find a participant ID,' giving concrete guidance on when to use an alternative tool. It also explains the campaignId targeting behavior and fallback to GROWSURF_CAMPAIGN_ID, so an agent knows exactly how to route the call.

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 and idempotentHint, so no contradiction. The description adds behavioral details: results are most recent first, offset acts as a cursor, and campaignId defaults to an environment variable. This enriches the agent's understanding of the operation's 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 sentences, front-loaded with the main purpose, followed by pagination and campaign targeting details. No redundancy or filler. Each sentence earns its place.

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

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

The description covers participant identification, sort order, pagination semantics including the response offset as cursor, and campaign targeting. The presence of an output schema means return values needn't be described. This is complete enough for an agent to invoke the tool correctly.

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

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

Schema coverage is only 20% (only campaignId has a description). The description compensates by explaining limit constraints (1-100, default 20), offset usage (skips logs), and how to identify the participant (by ID or email). It also clarifies the role of campaignId with a default. This adds meaning beyond the bare schema.

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

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

The description states a specific verb ('List') and resource ('participant's activity logs') with identification methods (ID or email) and sort order. It clearly distinguishes from sibling tools like growsurf_get_participant and growsurf_get_participant_analytics by naming the exact resource type.

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 operational context: how to identify the participant (ID or email), pagination parameters and defaults, and campaign targeting behavior. It does not explicitly mention alternative tools to avoid, leaving some inference to the agent, but the guidance is sufficient for correct 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 mark read-only/idempotent/non-destructive, and the description adds rich behavioral detail: date windows only affect optional series/email data, null milestones with partial state are unknown rather than proof of non-occurrence, and campaignId fallback. No 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 dense but every sentence carries distinct semantic value, starting with the core purpose and then layering optional behavior, edge-case semantics, and scoping rules. 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?

For a parameter-rich analytics call, the description covers identification methods, optional data selection, date filtering scope, default campaign targeting, and null-state interpretation. The output schema exists, so return value details are not required.

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 description adds substantial meaning beyond the schema: it defines include values (activation, series, email), explains activation milestone semantics, and clarifies that date-window parameters do not filter the base response. This compensates for the 75% schema coverage and clarifies the most subtle parameters.

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

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

Description opens with a specific verb and resource: 'Fetch analytics for one participant by GrowSurf participant ID or email.' It clearly delimits scope (one participant) and names the response contents, making it distinguishable from campaign-level analytics 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?

Clear context is provided: the tool is for per-participant analytics, with optional include values and campaign targeting behavior. It doesn't explicitly name alternatives or say when not to use it, but the one-participant scope and optional-data guidance are sufficient in context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds substantial behavioral context: it explains what 'activeProvider' means and when it is null, describes the repair reason for bounced/invalidated recipients, and states that status is reported per provider. This goes well beyond the annotations and gives an agent a clear mental model of the tool's behavior.

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

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

The description is dense and front-loaded with the primary action, then covers return fields and the campaign targeting nuance in a logical order. Every sentence adds value—no fluff, no repetition of annotation info. It is a single paragraph but well-structured and efficient for an agent to parse.

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

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

Given that an output schema exists (not shown but indicated), the description does not need to enumerate return format. It covers the key usage scenarios: looking up by ID or email, the provider context, the meaning of activeProvider, and failure states (bounce/invalidation). The default campaignId behavior is explicitly stated. An agent can select and invoke this tool correctly with no gaps.

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

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

Schema description coverage is only 33% (only campaignId has a description). The description compensates by explaining that participantId or participantEmail are identifiers, reinforcing the anyOf constraint, and fully explaining campaignId's default behavior. It adds meaning to the identifier parameters without going into format details, which is acceptable for a read tool. This strong compensation for low schema coverage merits a 4.

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

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

Description opens with a precise verb-resource pair: 'Get a participant's payout-destination status' and immediately clarifies scope (per provider, by ID or email). It lists specific return fields (status, confirmed email, legal recipient type, repair reason, activeProvider) that distinguish it from sibling tool growsurf_get_participant and analytics tools. The target ambiguity (campaignId vs default) is resolved in the last sentence.

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 the tool is for checking payout-related state, contrasting with siblings like analytics or activity logs, and explains the campaignId override. It does not explicitly name alternative tools or say 'when not to use', but the purpose is specific enough that an agent would know when to call it. Lacking an explicit exclusion statement keeps it at a 4 rather than 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the bar is lower. The description adds real value beyond annotations: the verificationStatus=VERIFIED semantic and its workflow implication (required before emailing participants), the exclusion of personal profiles/internal identifiers, and auth expectations.

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 zero waste. Purpose is front-loaded, followed by the verification-state caveat, the privacy exclusion, and auth requirements. Every clause earns its place.

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

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

Output schema exists and handles return values. For a 0-parameter read tool, the description covers the key operational facts: what it fetches, the verification prerequisite, what is NOT returned, and which credentials are needed. 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?

Zero parameters and 100% schema coverage, so the schema has nothing to document. With no params, the baseline is 4; the description correctly fills the semantic gap by explaining authentication context (API key vs OAuth) that shapes how input is resolved.

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

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

States a specific verb ('Fetch') + resource ('team') + scope ('bound to the API key or OAuth connection'). Among a long sibling list containing update_team and verification tools, this unambiguously identifies a read-only team retrieval operation.

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

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

Provides explicit prerequisites: requires GROWSURF_API_KEY and, notably, does NOT require GROWSURF_CAMPAIGN_ID — a useful signal for when this tool applies versus campaign-scoped siblings. Doesn't name alternatives outright, but as the only 'get team' tool among siblings this is a minor gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to cover safety. It adds value by specifying the output artifact (a code snippet) and the configuration context (participant auto-auth, window.grsfConfig), which are not in annotations. No 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?

One sentence with zero redundancy; the primary purpose and placement are front-loaded. Everything present 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?

Despite having an output schema, the tool description omits essential details about parameter usage and selection logic. With 7 undocumented parameters and multiple sibling snippet tools, the description is insufficient for an agent to confidently invoke this tool correctly.

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

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

Schema description coverage is 0% and the tool description provides no parameter explanations. With 7 optional parameters (hash, email, campaignId, affiliateJoin, etc.), the agent has no guidance on what values to provide or how they affect the snippet. The description fails 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 clearly states the tool generates a <head> snippet for participant auto-auth using window.grsfConfig, with a specific placement instruction. This distinguishes it from other snippet tools like growsurf_embeddable_element_snippet or growsurf_client_snippets by naming the purpose (auto-auth) and the configuration variable.

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 a placement instruction ('place before the GrowSurf Universal Code') but does not explain when to choose this tool over other snippet-related siblings. Given the large set of sibling tools, an agent would benefit from explicit selection criteria, which are absent.

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 agent knows this is a safe, non-destructive operation. The description adds the 'happy-path' qualifier and scopes to referral + affiliate, but does not disclose what the plan contains or any constraints on how it is generated. Given the annotations, a 3 is appropriate since the description is consistent but does not add meaningful behavioral context beyond the structured metadata.

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, concise sentence that immediately states the tool's purpose. It is front-loaded with the verb and outcome. While it is short, it is not overly verbose and does not waste words. The structure is appropriate for a simple guide generator, though it could afford to include a bit more detail without losing conciseness.

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

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

Given the tool has five parameters, a rich schema with enums and defaults, and an output schema exists, the description should provide enough context for the agent to know how to configure the plan. However, it offers only a vague 'happy-path' concept and program type, leaving the other parameters ambiguous. There is no explanation of what the plan will include or how the parameters influence it, making it incomplete for confident 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 schema description coverage at 0%, the description must clarify parameter meanings, but it fails to do so. The only hint is 'referral + affiliate' which maps to programType, but none of the other four parameters (singlePageApp, referralTrigger, webhookSecurity, participantAuthEnabled) are mentioned or explained. The schema provides enums and defaults, but the description does not add semantics or usage context for any parameter.

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

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

The description states a clear verb ('Generate') and a specific resource ('a guided, happy-path GrowSurf integration plan') and mentions the scope ('referral + affiliate'). This is not a tautology and conveys the tool's essential role. However, it does not explicitly differentiate itself from similar sibling tools like growsurf_mobile_sdk_guide or growsurf_api_library_snippets, which also appear to be guides.

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 explicit guidance on when to use this tool versus alternatives, such as the other guide-style tools (e.g., growsurf_mobile_sdk_guide). The purpose is implied but not stated with exclusions or conditions. The agent would have to infer that this is the correct guide based on the 'referral + affiliate' wording, but no when-to-use or when-not-to-use information is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds meaningful behavioral context: listed rewards are configurations, not evidence of participant earning, and the call defaults to GROWSURF_CAMPAIGN_ID when campaignId is omitted. This goes beyond the annotation coverage.

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 compact sentences carry the primary purpose, a critical caveat, an alternative tool reference, and the default parameter behavior. Every sentence earns its place with no redundant 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 single-optional-parameter, read-only listing tool with an output schema and supportive annotations, the description covers the key contextual needs: what is returned, what it does not imply, and how targeting works. No critical information appears 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 schema already documents that campaignId defaults to GROWSURF_CAMPAIGN_ID and can be populated with the id from growsurf_create_campaign. The description repeats part of this behavior rather than adding new parameter semantics, so the baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('program's configured rewards'), and clarifies it is about configured settings, not participant reward status. It also implicitly distinguishes itself from participant-related tools by pointing to growsurf_get_participant.

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

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

The description explicitly says when not to rely on this tool: these settings do not establish that a participant earned or received a reward, and directs the agent to growsurf_get_participant instead. It also explains the campaignId defaulting behavior, giving clear guidance for selecting the right target.

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, covering the safety profile. The description adds behavioral context beyond that: it notes that deleted programs are not returned and that GROWSURF_CAMPAIGN_ID is not required. Since the output schema exists, it doesn't need to detail return structure. This is solid complementary info.

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 first states the core purpose, the second gives usage context, and the third covers a behavioral nuance. The most important information (what it lists and when to use) is front-loaded. 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?

For a no-parameter list tool, the description is complete: it states what it does, when to use it, what it omits (deleted programs), and clarifies the environment variable requirement. With an output schema available, the agent has everything it needs to call and interpret this tool correctly.

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

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

The tool has zero parameters, so there is nothing to document, and the description adds no parameter details (which is expected). The note about not requiring GROWSURF_CAMPAIGN_ID clarifies a common context, but it's not about a parameter in this tool. Baseline for 0 params is 4, and nothing is missing.

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 action ('List') and the resource ('GrowSurf programs available to the bound team'). It explicitly differentiates itself from campaign-scoped siblings by noting it should be used first to select a 'campaignId' before calling those tools. This makes its purpose precise and non-overlapping.

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

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

It provides explicit when-to-use guidance: 'Use this first when you need to choose a campaignId before calling campaign-scoped tools.' It also clarifies that it does not require GROWSURF_CAMPAIGN_ID, which is a key trigger for when this tool is appropriate versus others. The exclusion of deleted programs adds a useful caveat for interpreting results.

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=false, so the safety profile is covered. The description adds behavioral context beyond annotations: it explicitly states that secrets are never returned, which is a crucial security-related behavior not captured in structured fields. It also clarifies the default campaignId behavior, though that is also in the schema. 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 concise sentences with zero waste. The core purpose and the critical secret-handling caveat are front-loaded, followed by the parameter behavior. Every sentence earns its place, and there is no redundant or fluff 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 simple list tool with one optional parameter, the description is complete. Annotations cover the read-only and safe nature, an output schema exists to document return values, and the description clarifies the campaign targeting and security guarantee. Nothing an agent needs to correctly invoke this tool 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 fully documents campaignId, including its default to GROWSURF_CAMPAIGN_ID. The description repeats this information ('Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID') without adding new semantics beyond what the schema provides. Since the schema carries the burden, a 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 clearly states the tool lists webhooks for a GrowSurf program, using a specific verb ('List') and resource ('webhooks'). It also mentions an important caveat (secrets never returned) and the campaign targeting behavior. This distinguishes it clearly from sibling webhook tools like create/update/delete/test, and from list_campaigns which lists campaigns, not webhooks.

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

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

The description implies usage context (read-only listing) and explains the campaignId targeting behavior, which helps the agent decide when to call it. However, it does not explicitly name alternatives (e.g., 'use growsurf_create_campaign_webhook to add webhooks') or state when NOT to use this tool. The sibling names make the distinction fairly obvious, but explicit guidance would elevate this to a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description reinforces the read-only nature. It adds meaningful context beyond the annotations by defining the state fields (connected, enabled, autoDisabled, connectUrl) and disclosing that autoDisabled means delivery stops until reconnection. Consistent with annotations, no 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?

Front-loaded with the purpose and readable, but slightly verbose — the field definitions and omission rule, while valuable, could be tightened. Every sentence earns its place, so the length is justified rather than padded.

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

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

Complete for a filtered-list tool: an output schema exists so return values are covered there, and the description explains the state semantics, the omission behavior, the read-only constraint, the alternative tool, and the targeting rule. 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?

Schema coverage is 100% and the single campaignId parameter is fully documented in the schema, including the default and the create_campaign hint. The description adds only a marginal targeting note ('Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID') that mostly restates the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb (List) + resource (every integration for a program) + scope, and enumerates concrete examples (Stripe, PayPal, Mailchimp, Slack, Zapier, Webhooks). The read-only caveat and connect-link routing differentiate it from siblings like growsurf_get_integration_connect_link and growsurf_integration_guide, so an agent can distinguish it without opening schemas.

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

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

Gives an explicit use case ('check whether an integration is connected before you act on it'), explains that inapplicable integrations are omitted, and names the alternative tool with the condition that selects it ('call growsurf_get_integration_connect_link for the link to hand the user'). Nothing is left to inference.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds valuable behavioral detail beyond those hints: newest-first ordering, the 1-100 limit with default 10, continuation via nextId, and the campaignId fallback to GROWSURF_CAMPAIGN_ID. No annotation contradiction.