affiliate_awin_get_programme_details

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

With no annotations, the description must disclose behavior on its own. It states that the tool returns 'the detailed programme envelope with raw Awin data preserved,' giving some transparency about the output format. However, it does not mention authentication requirements, potential errors, or any side effects, though the 'Fetch' verb implies a read-only operation.

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 each earning its place: what it does, when to use it, and what it returns. No fluff or repetition, and it is well-structured for quick scanning.

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

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

The tool is simple (2 params, no output schema, no annotations), and the description covers purpose, usage, and return envelope. However, it is incomplete because it omits the 'relationship' parameter semantics and provides only a vague description of the return format ('raw Awin data preserved'), leaving some ambiguity for an agent.

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 explains 'advertiserId' as 'a specific advertiser ID' but does not mention the 'relationship' parameter at all, leaving its meaning and impact on the fetch undocumented. This is a significant gap given the parameter is optional and has an enum.

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

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

The description uses a specific verb ('Fetch') and resource ('Awin programme details'), clearly scoped to a specific advertiser ID. It also enumerates the exact content (description, KPI, deeplink status, valid domains, commission range), which differentiates it from generic list or get tools and from siblings targeting other networks.

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 usage context: 'Use this before promoting a merchant when the user needs description, KPI, deeplink status, valid domains, and commission range.' This clearly states when to invoke the tool, though it does not explicitly mention when not to use it or name alternatives.

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