affiliate_monetizze_list_programmes

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

With no annotations, the description carries the full burden, but it only discloses that the tool lists programmes (joined or available) and returns an array. It does not clarify pagination behavior, authentication requirements, or how the joined/available distinction is controlled, leaving important behavioral details unspecified. The added nuance about 'available to join' is useful but not fully explained.

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

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

The description is three sentences and gets straight to the point, front-loading the action and scope. It includes useful examples and relational context without padding, making it efficient.

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 the absence of both annotations and an output schema, the description only gives a minimal return-type hint ('array of Programme records') and omits explanations for pagination/filtering parameters. The joined/available ambiguity is also unresolved, leaving significant gaps for a 6-parameter tool.

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

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

The description offers no guidance on the six schema parameters (limit, cursor, offset, search, status, categories) despite 0% schema coverage. None of these are mentioned, so the agent must infer their meaning from names alone, which is insufficient for correct invocation.

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 affiliate programmes on Monetizze, including both joined and available ones. It names Monetizze explicitly, distinguishing it from the many sibling list_programmes tools, and references companion tools for drill-down and activity, reinforcing its purpose.

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

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

It provides explicit trigger phrases ('which merchants am I working with?', 'what programmes do I have on Monetizze?') and states it is for a partner inventory. It also points to get_programme and list_transactions as related tools, effectively signaling when to use them instead.

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