create_tracked_link

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

With no annotations, the description carries the disclosure burden and does well: it states the operation is a write that persists a log entry and that downstream traffic, spikes and conversions are attributed to it. It still omits permission requirements, whether duplicate source+campaign pairs are deduped or error, and whether the call is idempotent.

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 purpose then usage then follow-up call; no filler. Every sentence changes what the agent does.

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?

There is no output schema, and the description does not say the call returns the shareable tagged link the agent needs to publish — that is the one notable hole. Otherwise purpose, usage policy and follow-up workflow are complete for a 5-parameter creation tool.

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

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

Schema description coverage is 100%, so all five parameters are already documented with defaults and examples (medium default 'social', url default '/'). The description only adds the UTM framing and the single-campaign constraint; it does not explain how source/medium/campaign map to UTM parameters beyond what the schema states.

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 UTM-tagged link') plus the side effect ('log it so later traffic... credited to it'), which separates it cleanly from siblings like add_annotation or create_funnel. An agent can tell exactly what this produces and why.

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

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

Gives a prescriptive usage rule ('Use a new link for every post, email or ad you publish') and explicitly sequences the follow-up tool: 'After it is published, call add_annotation...'. This is when-to-use plus named alternative/next action, not inference.

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