make_affiliate

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

Annotations already flag non-readonly and non-idempotent; the description reinforces and expands with concrete context: repeated calls can duplicate the effect, auth is injected server-side so the model never supplies tokens, calls are throttled under LearnWorlds' 30-per-10s cap and retried on 429/5xx, and non-2xx statuses surface as tool errors with 401/403/404/422 mappings. No contradiction with annotations — the write claim aligns with readOnlyHint=false and the non-idempotency claim aligns with idempotentHint=false.

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?

Labeled sections (Behavior, Parameters, Returns, Use when) with the verb and endpoint front-loaded make this highly scannable. It runs longer than average, but every section carries actionable information — idempotency, auth, throttling, error mapping — 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?

For a mutating tool with no output schema and a nested body, the description closes nearly every gap: side effects in the live school, non-idempotency, auth handling, rate limits, exact return shape (HTTP status + JSON body), and error semantics. The only minor omission is that the pre-check read tool is left generic ('a 🟢 read tool') rather than naming get_affiliates, but this does not meaningfully impair an agent's ability to call 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?

The schema documents id and the nested body fields well, but the body object itself has an empty description (50% top-level coverage). The description compensates for exactly that gap by disclosing that the whole payload goes in the single body argument, is forwarded verbatim, and is in practice required even though the spec marks it optional — genuinely useful nuance the schema does not convey.

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+resource: making a user an affiliate, backed by the explicit endpoint POST /v2/affiliates/{id}. It is unmistakably distinct from the many get_* affiliate siblings because it is the only write operation among them, and it visibly differentiates itself from the related read 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?

Gives an explicit activation condition ('Use when: only when the user asked to create this') and a required precondition (verify the target exists and is not already an affiliate with a 🟢 read tool). It names related affiliate tools but stops short of mapping each alternative to a specific condition, so the when-not logic is largely implied rather than spelled out.

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