Integration Guide

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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