LinkJolt

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

Beyond readOnly/openWorld annotations, it discloses the external fetch (a live page of the site), the plan gate, and the shape of the response including that 'next' names the first remaining action. That is real behavioral context an agent cannot get from the annotations alone, and nothing conflicts with them.

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?

Purpose is front-loaded and every clause carries information, but the middle sentence is long and stacked with parentheticals ('the one tool that shows test sales'), which slows scanning. Slightly tighter phrasing would earn a 5.

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?

With no output schema, the description still tells the agent what comes back: per-check sentences plus a 'next' item naming the first remaining step. Combined with the plan prerequisite and the two run-timing triggers, an agent has everything needed to invoke it 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?

Schema coverage is 100% for the single optional url parameter, so the baseline is 3. The description earns one extra point by explaining the default ('the business website unless url is given') and framing why you would target a specific page, e.g. a pricing page where the tag must be present.

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 ('Check that affiliate tracking works') and then spells out the mechanism: fetches a page, looks for the account tag, and reports on script execution, payment-platform connection and test-purchase arrival. It also carves itself out from siblings by noting it is 'the one tool that shows test sales', which separates it from get_setup_status and get_tracking_instructions.

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 explicit triggers: run it after the script is deployed, and again after the person buys once in test mode through an affiliate link. It also states the eligibility condition (Pro plan or higher, or a new account without a plan), so an agent knows when the call is appropriate and when it will be rejected.

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

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

Goes well beyond the annotations: the campaign is active immediately, is publicly listed in Discovery unless isPublic is false, plan limits apply, and Pro plan plus live keys are required. It also discloses the return payload (campaign plus joinUrl) and the sharing semantics of that join link — exactly the mutation side effects an agent needs.

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?

Front-loads purpose, then the return value, the confirmation rule, the side effects, and the plan prerequisites in descending order of importance. Five sentences, each carrying a distinct fact; nothing is repeated from the name or title.

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 13-parameter, non-idempotent, world-visible write operation with no output schema, the description covers prerequisites, side effects, quota, user confirmation, and the return shape. There is no output schema, yet the agent still learns the response includes the campaign and joinUrl.

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 coverage is 100%, so the schema already carries full parameter documentation and the baseline is 3. The description adds only light meaning beyond that — the behavioral consequence of isPublic and the fact that recurring commissions pay on renewals — without adding format, range, or interaction detail the schema lacks.

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?

Opens with a specific verb and resource ('Create an affiliate campaign') and immediately qualifies the resource in business terms — what affiliates earn per sale and where links send people — so the agent knows exactly what the object is. It is clearly distinguishable from update_campaign, get_campaign, and list_campaigns by verb.

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 concrete pre-call guidance ('Confirm the commission with the user before calling') plus prerequisites ('Requires Pro plan or higher; live keys only') and a quota constraint ('The plan's campaign limit applies'). It doesn't name alternatives, but the create/read/update sibling split is unambiguous from the name alone.

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

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

Goes well beyond the annotations by disclosing real side effects: a live conversion notifies the merchant's team and emails the credited affiliate, while test keys do neither. Combined with the plan/permission requirement, an agent knows the blast radius before calling.

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 short sentences, each earning its place: what it does, what side effects it triggers, and what auth/test-mode constraints apply. No filler and the core action is front-loaded.

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 10-parameter mutation with no output schema, the description covers the important behavioral surface — side effects, plan/write requirement, test-mode behavior. It does not mention what the call returns (e.g. a conversion id) or error behavior on duplicate orderId, but those are marginal given the rich schema.

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 every parameter including amount units, currency defaulting, duplicate orderId rejection and parentConversionId is already documented. The description only echoes 'a sale to credit to an affiliate' and adds no syntax or format detail beyond the schema; baseline 3 applies.

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 ('Manually record a conversion') and immediately disambiguates with a parenthetical defining a conversion as a sale credited to an affiliate. This clearly separates it from list_conversions and update_conversion without opening either schema.

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 word 'Manually' signals the use case (recording a sale that didn't arrive via automatic tracking), and prerequisites are given explicitly: an Ultimate or Scale plan key with write access, plus the note that test keys work but store test data. It stops short of naming an alternative tool or an explicit when-not condition.

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

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

Beyond the annotations (which only declare it is not read-only and is idempotent), the description discloses that it writes to an external payment platform (Stripe/Polar/Creem), which field values are real vs. cosmetic in each mode, the plan/key permission requirement, and the edge case that a missing platform connection returns a connect link rather than creating anything.

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?

Front-loaded with the outcome, then modes, then prerequisites — good ordering and no filler. It is a dense run-on paragraph with long clauses, which slightly hurts scannability for a 16-parameter tool, but every sentence carries information.

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 16-parameter, dual-mode, external-write tool with no output schema, it covers the essentials: mode selection, required permission tier, provider defaults, what happens on failure (connect link), and a confirmation step. Nothing an agent needs in order to call this correctly is missing.

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 coverage is 100%, so the baseline is 3; the description earns a bump by explaining the mode-dependent default provider ('the one it creates codes in unless provider is given') and the promo_ id requirement for typed Stripe codes. Most individual field meanings (percentOff, amountOff with currency, duration values) are already in the schema, so it is additive rather than essential.

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?

Opens with a concrete verb+resource+benefit ('Give an affiliate a discount code so sales using it are credited to them') and immediately distinguishes itself from list_coupons by describing creation/registration rather than listing. It also splits its own two modes into named operations (create in provider vs. register existing), so an agent knows exactly what this tool does.

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?

Explicitly states the two usage modes and the switching condition: 'With createInProvider true, LinkJolt creates the code... Without it, the code must already exist in the payment platform and this registers it.' It adds prerequisites (Ultimate or Scale plan key with write access; a test key only registers) and a procedural instruction ('Confirm the code, the discount and the affiliate with the person first').

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds non-obvious behavioral context the annotations cannot convey — a Pro plan or higher entitlement requirement — which is exactly the kind of gating an agent needs before invoking.

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?

Two short sentences with no waste: the primary purpose and id formats come first, then the entitlement constraint. Nothing is repeated from the schema or annotations.

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 single-parameter read whose output schema is provided and whose safety profile is in annotations, the description covers what's needed: provenance of the id, accepted formats, and the plan gate. Minor gaps remain around error behavior for invalid or cross-account ids, but nothing essential is missing.

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 coverage is 100%, so baseline is 3, but the description goes beyond the schema's generic 'composite id returned by the search tool' by spelling out the four accepted prefixes. That prefix enumeration is genuine added meaning for constructing a valid id.

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 (fetch) and resource (the full record behind a search result id), and enumerates the id namespaces it accepts (campaign:, affiliate:, coupon:, conversion:). This distinguishes it clearly from sibling getters like get_campaign or list_coupons, which target a known entity type rather than a search-result composite id.

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?

Explicitly ties the tool to a preceding search result id, which tells the agent when to use it (after search) and what input it expects. It doesn't name an alternative for cases where the agent already knows the entity type, but the linkage to search is a clear usage condition.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds useful context about the Pro plan requirement and the affiliate count in the response, but it does not describe error behavior or what 'full detail' includes beyond that.

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 two short sentences with no wasted language. The main purpose is front-loaded, and the plan requirement follows naturally.

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 simple single-parameter read tool with annotations and no output schema, the description covers the core retrieval behavior and an important prerequisite. It could be slightly more complete by mentioning behavior when the campaign is missing or the plan is insufficient, but it is adequate overall.

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%, and the single campaignId parameter is already documented in the schema. The description does not add syntax, format, or validation meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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 and resource: 'Get one campaign with full detail, including affiliate count.' It clearly distinguishes a single-campaign lookup from list-style siblings like list_campaigns, though it does not explicitly name alternatives.

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 implies usage by specifying retrieval of one campaign and adds a prerequisite: 'Requires Pro plan or higher.' However, it does not explicitly say when to prefer this over list_campaigns or what to do if the plan requirement is not met.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by stating 'Needs no LinkJolt account' — an auth prerequisite the agent cannot infer from annotations, and one that matters for a connector otherwise operating inside an authenticated account.

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?

Two sentences: the first enumerates the payload, the second the trigger condition. Front-loaded with the resource, zero filler, and no restatement of the title or annotations.

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?

With no output schema and no parameters, the description carries the full burden of describing results, and it does so concretely — prices, per-plan tracked-sales limits, per-plan connector capabilities, and free-trial behavior. An agent knows exactly what it will get and whether to call it.

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 tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly does not waste words on inputs and instead spends them on return content.

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 resource (LinkJolt plans and prices) plus the exact contents returned: monthly tracked-sales limits, per-plan connector capabilities, and free-trial mechanics. No sibling tool deals with pricing, so it is unambiguously distinguishable from the campaign/affiliate/stat operations in the sibling list.

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 trigger: 'Use it when someone asks what LinkJolt costs or which plan they need.' That is a clear usage context. It stops short of naming alternatives or when-not conditions, though for a zero-parameter pricing lookup there are effectively none.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured context: client-dependent rendering (interactive card in Claude/ChatGPT vs JSON elsewhere) and an entitlement prerequisite ('Requires Pro plan or higher'), both of which affect how an agent should invoke and present the result.

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 the data payload and followed by rendering and entitlement notes. Every sentence carries distinct information, though the card-rendering clause is only marginally relevant to tool selection.

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?

An output schema exists, so return-value explanation is not required, and the description covers scope (this month), delivery format, and the plan prerequisite. The only remaining gap is the absence of routing guidance relative to sibling aggregation tools.

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 tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a parameterless tool is 4; the description adds the useful note that scope is fixed to the current month.

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 names a specific resource ('this month's program snapshot') and enumerates the exact contents (revenue, conversions, commissions, top affiliates, recent conversions), so an agent knows precisely what comes back. It does not, however, contrast itself with close siblings like get_stats or list_conversions, so differentiation is left to inference.

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?

'in one call' implicitly signals this as a consolidated alternative to several separate calls, which is useful, but the description never explicitly says when to prefer it over get_stats or list_conversions. Usage is implied rather than stated.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real behavioral context beyond them: a plan-tier entitlement gate, the fact that the returned business name may be an auto-generated placeholder derived from email domain or first name, and that Stripe/payment connection is browser-only with connectLinks supplying the one-click URL. Nothing contradicts the annotations.

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?

Front-loaded with the resource and its contents before any conditional guidance, then ordered by actionability: when to call, placeholder-name handling, payment connection constraint, eligibility. The parenthetical step list and field names are dense but every clause carries information an agent would otherwise have to guess.

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, so the description carries the return-value burden and does it: it lists the returned sections, explains the meaning of the needsDetails flag and connectLinks, and discloses the plan prerequisite. An agent has enough to call it correctly and interpret the result without additional tools.

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 tool takes zero parameters, so the baseline is 4 and there is no parameter syntax to disambiguate. The description instead spends its space on field-level semantics of the response (needsDetails, connectLinks), which is useful but not parameter documentation.

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?

Names a specific resource (account's affiliate-program setup state) and enumerates the concrete payload: business name/website, the five launch steps plus the next one, tracking script tag and whether it has been seen, and per-campaign join links. The phrase 'Call it first when helping someone set up or launch' separates it from siblings like get_program_overview or check_tracking.

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?

Explicitly says when to call it ('first when helping someone set up or launch'), states an eligibility precondition ('Requires Pro plan or higher, or a new account that has not picked a plan yet'), and gives branching guidance for the needsDetails flag and for payment connection, which can only be completed by the person in the browser.

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

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

Annotations already declare this a safe, read-only, closed-world call, so the description doesn't need to re-establish that. It adds two things structured fields don't: an entitlement prerequisite (Pro plan) that will cause failures if unmet, and a return-shape detail ('money also listed per currency in byCurrency') that an agent can use to interpret the response.

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?

A single front-loaded sentence that leads with the verb and the metric list, then the optional filter, then the prerequisite. Dense but every clause carries information; the parenthetical date-range note is slightly awkwardly embedded but not wasteful.

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?

With no output schema, the description must convey return contents, and it does so by listing the metrics and the byCurrency breakdown. Gaps remain around aggregation granularity and the default period when no range is given, but nothing essential for a correct call is missing.

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% and both params are documented as ISO dates, so the baseline is 3. The description only adds that the range is optional and that 'from'/'to' form a pair; it doesn't state what happens when only one bound is supplied or what default window applies when both are omitted.

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?

Names a specific verb ('Get aggregate stats') and resource ('for the brand') and enumerates the metrics returned (revenue, commissions, conversions, clicks), which distinguishes it from the list_* siblings that return raw records. It does not explicitly name a sibling alternative, but the aggregate framing is clear enough that an agent won't confuse it with list_conversions or get_program_overview.

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 real usage gate ('Requires Pro plan or higher') and clarifies that the date range is optional, so an agent knows it can call this with no arguments. No explicit when-not or named alternative, which keeps it short of a 5, but the context is sufficient to decide whether and how to call it.

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

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

Annotations already establish that this is a safe, read-only, non-destructive, non-open-world operation. The description adds useful context beyond annotations by noting the included related data (members, campaigns, goals) and the Scale plan requirement. It stops short of describing error behavior or pagination, but the annotation coverage lowers the burden.

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 two sentences with no wasted words. The core action and returned scope are front-loaded, followed by the prerequisite, making it easy to scan.

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?

Given the low complexity, single required parameter, 100% schema coverage, and rich read-only annotations, the description is complete enough. It explains what is returned and the plan prerequisite without needing an output schema.

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%, and the sole parameter teamId is documented as 'The team id' in the schema. The description does not add syntax, format, or validation details beyond the schema. A baseline score of 3 is appropriate because the schema already carries the parameter semantics.

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 states a specific verb and resource: 'Get one Affiliate Team.' It also clarifies the returned scope by mentioning members, campaigns, and goals, which helps distinguish this from list_teams. However, it does not explicitly name or compare against sibling 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?

The only usage-related information is the prerequisite 'Requires the Scale plan.' There is no guidance on when to use this tool versus list_teams, get_campaign, or other related tools. The agent must infer that a teamId is needed to fetch a single team.

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

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

Annotations already establish that this is a read-only, non-destructive, non-open-world operation, and the description adds important behavior beyond that: the output is personalized with the account's tracking script and webhook address, and access requires Pro plan or higher or a new unpicked account. It also discloses platform-specific webhook behavior for Stripe, Paddle, Polar, and Creem without contradicting the annotations.

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 front-loaded with what the tool returns and then adds usage, connection, and plan prerequisites. It is dense and long for a single paragraph, but most clauses carry actionable context rather than filler.

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 one-parameter read-only tool with no output schema, the description is complete: it explains what the return contains, how to use it, the relevant next step, platform connection caveats, and access prerequisites. An agent has enough context to call it correctly and understand the result.

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 coverage is 100%, so the enum and platform descriptions already carry most of the parameter meaning. The description adds useful context that the selected platform determines whether a manual webhook step is needed, especially for Stripe, Paddle, Polar, and Creem, which goes beyond the schema.

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?

It states a specific verb and resource: returns tracking instructions for affiliate sales on a chosen payment platform, personalized with this account's script and webhook. It also makes clear the return is the same text shown on the Integrations page for AI assistants, which distinguishes it from setup/checking tools like check_tracking.

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 explicitly says to use it to add the tracking script to the site and pass the referral to checkout, then use check_tracking to confirm it works. It also explains that platform connection happens in the browser and that manual webhook steps are only needed when that connection is not used.

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

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

Annotations only declare the generic safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=true). The description adds materially: a real email is sent under the business's name, the call is refused for duplicate/campaign-existing recipients, it is rate limited to 10 per minute, and it requires a Pro plan. These are exactly the traits an agent cannot infer from the structured fields.

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?

Four short sentences, front-loaded with the action, then the user-confirmation requirement, then failure modes, then rate and plan limits. No sentence is redundant.

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 mutation tool with no output schema, the description covers side effects, refusal cases, rate limits, and plan gating, which is strong. It stops short of saying what a successful call returns or where the invitation state becomes visible, a minor remaining gap.

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 coverage is 100%, so name, email, and campaignId are already documented. The description adds only a soft constraint (verify the address and campaign with the user) and no format or semantic detail beyond the schema, which is the expected baseline-3 case.

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, and scope: email ONE person an invitation to join a campaign as an affiliate. The 'one person' scope distinguishes it cleanly from list_affiliates and update_affiliate_status, and no sibling performs the same action.

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 explicit preconditions (confirm address and campaign with the user first) and explicit refusal conditions (already on campaign, already has a waiting invitation), plus a plan prerequisite. The only gap is that it never names an alternative tool for adjacent tasks such as bulk or re-inviting.

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

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

Annotations already declare this as a non-destructive read operation, and the description adds meaningful context beyond them by stating the plan requirement and hinting at returned fields (earnings and click counts). It does not cover pagination behavior or full response structure, but the added entitlement and return-content details are useful.

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 two tight sentences with no wasted text, and the core operation is front-loaded before the plan requirement. Every sentence contributes useful information.

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?

Given the rich schema and read-only annotations, the description is largely sufficient: it identifies the resource, plan requirement, and some return content. It could be more complete by clarifying pagination or when to choose this listing tool over related reporting tools.

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 in the schema. The description only vaguely implies campaign filtering with "across your campaigns" and adds no syntax or behavioral nuance beyond the schema.

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 states a specific verb and resource: "List affiliates," with scope across campaigns and returned data such as earnings and click counts. It is clearly distinguishable from sibling list tools by resource, though it does not explicitly name alternatives or exclusions.

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 gives a useful prerequisite ("Requires Pro plan or higher") but does not explain when to use this tool rather than related tools such as get_stats, list_payouts, or update_affiliate_status. Usage is implied by the tool name and description rather than explicitly guided.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description adds two facts the agent cannot get from structured data: the read-only nature is a deliberate assistant limitation rather than just a hint, and the tool is plan-gated on Scale. It doesn't mention pagination defaults or authorization scope, which the schema partially covers.

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 short sentences, each carrying distinct information: what it does, what it deliberately doesn't do, and what it costs to access. Nothing is padded and the core purpose is front-loaded.

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 zero-required-parameter read tool with a rich, fully described schema and safety annotations, the description covers purpose, plan gating, and the approval exclusion. The only marginal gap is that it doesn't hint at what an award record contains or how reconciliation should interpret status values, but that is minor without an output schema.

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 six filters (page, limit, status, teamId, periodKey, affiliateId) are already documented in the schema. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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 (list bonus awards) plus the scope 'across all teams' and a use case (reconciliation). It doesn't need to differentiate from a close sibling because no other award-related tool exists, though it also doesn't position itself against list_payouts or list_team_goals which could cause confusion about which financial data lives where.

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 clear context for calling it (reconciliation), an explicit exclusion ('approving awards is deliberately not available to assistants'), and a hard prerequisite ('Requires the Scale plan'). No alternative tool is named for award mutation, but the exclusion effectively tells the agent not to attempt approval.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real value beyond that: results are scoped to the brand owning the API key, responses include stats, and a Pro plan is required — none of which appear in the annotations.

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?

One compact sentence covering resource, scope, and return shape, followed by a short plan requirement. Front-loaded and waste-free, though the parenthetical scope clause is slightly dense.

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?

With no output schema, 'with stats' usefully signals what comes back, and the plan prerequisite prevents a failed call. For a three-optional-parameter list tool this is nearly sufficient; only explicit sibling routing is missing.

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 coverage is 100%, so page, sort, and limit are fully documented with defaults and the max-100 cap. The description adds no pagination or sort semantics of its own, which is acceptable given the schema does the work, but nothing extra is contributed.

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 (List) and resource (affiliate campaigns) plus the exact scope: the LinkJolt account tied to the API key. The singular sibling get_campaign is implicitly distinguished by 'List', though the description never names it explicitly.

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 prerequisite 'Requires Pro plan or higher' is a useful gating condition, but there is no guidance on when to pick this over get_campaign for a single record or other list_* siblings. Usage is only implied by the verb.

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

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

Annotations already establish read-only, non-destructive, closed-world behavior, so the description need not repeat safety semantics. It adds useful access context with the Pro plan requirement and clarifies what a conversion represents ('tracked sales').

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 only two sentences and front-loads the core purpose and filters. Every sentence carries useful information with no wasted wording.

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 list tool with no output schema, full parameter documentation, and annotations covering safety, the description is largely complete. It could mention pagination or return shape, but those details are either schema-covered or obvious for a listing operation.

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 eight parameters are already documented in the schema. The description summarizes the main filter groups but does not add syntax, defaults, or constraints beyond what the schema provides, making the baseline 3 appropriate.

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 the specific verb 'List' with the resource 'conversions (tracked sales)' and names the supported filter dimensions. This clearly distinguishes it from mutation siblings like create_conversion and update_conversion.

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 states the filtering context and adds a prerequisite ('Requires Pro plan or higher'), which helps an agent decide whether the call is available. However, it does not explicitly name alternatives or when not to use this tool.

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

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

Annotations already declare the tool read-only and non-destructive. The description adds the plan-tier gating, which is valuable. It says nothing about the response contents, pagination metadata, or what happens on a lower plan.

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?

Two short sentences, front-loaded, with no wasted words.

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?

This is a simple read-only list tool with full schema coverage, so it is mostly adequate. However, with no output schema, the description does not say what coupon fields are returned or how pagination totals appear.

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 coverage is 100% and documents defaults and limits. The description adds no parameter information, so the baseline of 3 applies.

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?

"List registered affiliate coupon codes" gives a specific verb and resource. It is distinct from create_coupon by verb alone, but it does not explicitly set itself apart from siblings such as search or fetch.

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 Pro plan requirement is a useful prerequisite. There is no guidance on when to use the code parameter versus a general search, and no mention of the search/fetch alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered; the description adds the non-obvious entitlement gate (Pro plan), which is genuine behavioral context. It omits pagination behavior and return shape, which are not in annotations.

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?

Two short sentences, purpose first, prerequisite second — zero filler and nothing an agent must sift through.

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, yet the description never says what a payout record contains or how pagination/results are returned. The plan gate is covered, but for a 7-parameter listing tool with no output schema the return-value gap leaves it only minimally adequate.

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% with all seven filters, defaults, and the 100-result cap documented inline. The description adds nothing beyond the schema, so the baseline 3 applies.

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 (list the affiliate payout queue) plus a stated purpose (reconciliation), which distinguishes it from adjacent list_* siblings like list_conversions and list_awards. It stops short of naming which sibling to prefer for payout-adjacent data.

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?

'For reconciliation' gives a clear usage context, and 'Requires Pro plan or higher' is a real prerequisite an agent must check before calling. No explicit exclusions or alternative-tool routing are provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a non-obvious operational constraint, the Scale plan requirement, plus an indication of what is returned (targets with current-period progress), which is real value beyond the annotations.

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?

Two short sentences with zero waste, front-loading the action and the returned content before the prerequisite. Nothing is padded or repeated.

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 one-parameter read tool with no output schema, the description covers purpose, returned content and a plan gate. The only gap is that it never states behavior when the team has no targets or how progress is scoped to the current period.

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?

With a single required teamId parameter at 100% schema coverage, the schema already carries the parameter meaning. The description adds nothing about the id format or scope, so the baseline of 3 applies.

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 gives a specific verb and resource ('List a team's targets') plus the returned content ('current-period progress'), which separates it from list_teams and the other list_* siblings. It stops short of naming an alternative tool explicitly, so it is clear but not sibling-differentiating at the highest level.

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?

'Requires the Scale plan' is a genuine prerequisite that tells the agent when the call will fail rather than when to choose it. There is no guidance on when to prefer this over other listing tools or on what to do if the plan requirement is unmet, leaving usage largely implied.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's job is to add context — and it does, disclosing the returned payload shape (rosters, targets, pending awards) and the plan entitlement requirement. That entitlement note is meaningful behavioral information not present in the annotations.

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?

Two tight sentences, zero filler, with the payload scope front-loaded and the prerequisite second. Every clause carries information the agent needs.

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?

With no output schema, the description usefully enumerates what comes back (rosters, targets, pending awards), which is exactly the gap an agent would otherwise hit. Pagination and the plan gate are covered; only the absence of output structure detail keeps it from a 5.

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% with only page and limit, both fully documented in the schema. The description adds no additional parameter semantics, so the baseline 3 applies.

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 ('List Affiliate Teams') and further specifies what the listing includes: rosters, targets and pending awards. It is clearly distinguishable from the singular get_team and from list_team_goals/list_awards, though it does not explicitly name a sibling as an alternative.

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?

Adds a real eligibility gate — 'Requires the Scale plan' — which tells the agent when this tool can be used at all. It does not spell out an explicit alternative ('use get_team for one team'), but the list-vs-get distinction is clear from the naming and content scope.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false; the description adds valuable context beyond them: the recommendations are derived from LinkJolt's published benchmarks of real SaaS programs, no auth/account is required, and it also computes per-sale affiliate earnings. It does not detail output shape, but the annotation coverage lowers the burden.

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?

Front-loaded with the core action, followed by the output set, the data source, the no-account note, and the use case. Dense but every clause carries information; only the earnings-per-sale clause slightly duplicates the output enumeration.

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 read-only advisory tool with no output schema, the description tells the agent what kind of recommendations come back and where they are sourced from, which is enough to call it correctly. A brief note on whether results are deterministic or vary by currency/billing would round it out.

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 four parameters are already documented with examples and a default ('default monthly', 'default USD'). The description hints at the role of commissionPercent via 'what an affiliate would earn per sale at typical rates' but adds no syntax or constraint detail beyond the schema. Baseline 3 applies.

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 ('Plan an affiliate program for a product before launching it') and enumerates the concrete outputs: commission rate, renewal payout policy, affiliate approval approach, and per-sale earnings. This is clearly distinguishable from sibling tools like create_campaign or get_program_overview, which are operational rather than advisory.

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?

Explicitly names the triggering question ('when someone asks what commission to offer or how to structure a program') and adds a precondition not visible in the schema ('Needs no LinkJolt account'). It stops short of naming alternatives or exclusions, but no sibling overlaps this planning function.

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

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

Annotations already mark the tool read-only and closed-world. The description adds that it returns ids rather than full records, that results are scoped to the caller's own program, and that a Pro plan or higher is required. Ranking, result limits and pagination are not covered.

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, each earning its place. There is no redundancy.

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?

This is a simple one-parameter read tool with an output schema and annotations. The description covers scope, searchable fields, the output relationship to fetch and the plan requirement. Little else is needed.

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 describes query only as search text of at least 2 characters. The description adds which fields the text matches: names, emails, coupon codes, order ids and customer names. That tells the agent what kinds of query strings are meaningful.

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: free-text search over the caller's own LinkJolt affiliate program. It enumerates the searchable entities (campaigns, affiliates, coupons, conversions), which sets it apart from list_* and get_* siblings. It also names its relationship to fetch.

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?

Opens with "Use this to find records... by free text" and explains that results feed into the fetch tool, which is a clear workflow. It also states the Pro plan prerequisite. It does not say when to prefer list_affiliates, list_coupons and similar tools for structured enumeration over free-text search.

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

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

Goes well beyond annotations: it discloses the downstream effects of approve (email link, coupon when applicable), the irreversibility of reject ('cannot apply again, and only the dashboard can let them back in'), and the boundary against approving sales/commissions. Annotations flag destructiveHint and idempotentHint, and the description supplies the consequences that make those hints actionable.

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?

Front-loaded with the decision and the discovery path, then effects, then constraints. Dense but each sentence carries distinct information; the parenthetical about list_affiliates is slightly bulky but functional.

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?

No output schema exists, and the description covers what an agent would otherwise need to infer: what happens on each branch, what is irreversible, plan gating, and the confirmation requirement. Nothing material is missing for a 3-parameter mutation.

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 coverage is 100%, so baseline is 3; the description earns an extra point by explaining what each action actually causes rather than restating the enum, and by clarifying that campaignId is the campaign the affiliate applied to. No format/syntax detail for the IDs is added, so it stops short of a 5.

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 paired verb (approve/reject) on a specific resource (an affiliate's application to a campaign) and scopes it to 'waiting for review'. An agent can distinguish this from update_campaign, invite_affiliate, or update_conversion without opening a schema.

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?

Explicitly routes discovery through a sibling: 'list_affiliates with status pending shows who is waiting'. Adds a hard prerequisite ('Confirm each decision with the user before calling') and an eligibility gate ('Requires Pro plan or higher'), plus an exclusion ('This never approves sales or commissions').

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

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

Goes beyond the annotations by explaining the visible effect (affiliates see the name on the join page and in emails) and the gating conditions (plan tier, live keys). It does not state what happens to a field that is omitted — whether the existing value is preserved or cleared — which matters given the partial-update framing and idempotent/destructive hints.

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 short sentences: what it sets, who sees it, then constraints. The purpose and optionality come first, prerequisites last — zero filler.

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?

Covers purpose, effect, optionality, and access constraints, which is sufficient for a 2-optional-param update with no output schema. The remaining gap is the omission/clearing semantics of a partial update, which an agent would need before deciding whether to send one field only.

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 coverage is 100%, so both parameters are already documented with examples and the https:// normalization rule. The description adds only indirect meaning for businessName (its audience visibility) and nothing new about the website field, so this sits at the baseline.

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 (Set) and resource (business name and website on this LinkJolt account) with the exact fields it mutates. The resource is clearly distinct from siblings like update_campaign or update_affiliate_status, so an agent can distinguish it without opening the schema.

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?

"Send either or both" clarifies that no parameter is required and that partial updates are acceptable. It also gives real prerequisites (Pro plan or higher, or a new unplanned account; live keys only), which is strong context, but it never names an alternative tool or a when-not-to-use condition.

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

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

Annotations only say this is destructive, idempotent and open-world; the description adds the substantive consequences: it is a partial update ('Send only what changes; everything else stays as it is'), changes are immediately visible to affiliates, and the response includes the campaign plus a `changed` field listing fields actually modified. That is real behavioral context beyond what any structured field conveys.

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?

A single dense paragraph, front-loaded with the verb and resource, then the mutable-field list, then the partial-update rule, then caveats. Nearly every clause maps to a distinct parameter or constraint, but the enumeration is long enough that tightening a few entries (e.g. the recurring-commission cluster) would improve scanability.

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 15-parameter mutation tool with no output schema, it covers the full picture: what can change, that only changed fields need sending, plan and key prerequisites, the affiliate-visibility side effect, and the shape of the return value. Nothing an agent needs in order to call this correctly is missing.

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 coverage is 100%, so the schema already documents all 15 parameters and the baseline is 3. The description earns an extra point by grouping the patchable fields into meaningful clusters and clarifying semantics that matter for invocation — e.g. 'inactive to pause it' and the partial-update rule that determines which params to send — though it still largely mirrors schema text.

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?

Opens with a specific verb+resource ('Change an existing campaign') and then enumerates exactly which attributes are mutable (name, description, targetUrl, status, commission, Discovery listing, auto-approval, recurring terms). It also draws a hard boundary around what this tool does NOT touch, so an agent can distinguish it from create_campaign, update_conversion, or dashboard-only operations without opening a schema.

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?

Explicit about when to use it and what to do instead: 'Commission tiers, coupon codes, files and prices are changed on the dashboard.' It also states required preconditions (Pro plan or higher, live keys only) and a mandatory confirm-with-user step before invoking — exactly the routing information an agent needs.

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

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

Goes well beyond the destructiveHint/idempotentHint annotations: refunded conversions are terminal, the >5x-sale guard refuses with commission_above_sale and changes nothing, approval queues the commission for the next automatic payout run (Stripe only, at least a day later, PayPal/Wise paid by hand), and rejection removes it from the queue. The closing 'never sends money itself' sets the expectation for any agent tempted to report a payment as made.

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?

Front-loaded with the action and preconditions, then the refusal path, then side effects. It is long for one tool but nearly every clause carries operational weight; the Stripe/PayPal/Wise parenthetical is the one detail that could be trimmed without loss to tool selection.

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 destructive, idempotent mutation with no output schema, the description covers auth requirements, terminal states, the guard/confirmation loop including the returned error sentence, and downstream payout side effects. An agent has everything needed to call it safely and explain outcomes to a user.

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 coverage is 100%, so the baseline is 3; the description adds real meaning on top by explaining the conditional workflow around confirmAboveSale (only after user confirmation of the returned sentence) and the consequence of the status choice on payout queues. conversionId semantics remain purely schema-level, which is fine for an identifier.

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 pair and resource ('Approve or reject a pending conversion'), immediately distinguishing it from create_conversion and list_conversions in the sibling set. The 'pending' qualifier further narrows the scope of what it acts on.

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 clear preconditions (Ultimate or Scale plan key with write access, conversion must be pending) and an explicit escalation path: set confirmAboveSale=true only after the user has seen the commission_above_sale message and confirmed. It does not explicitly route the agent away from sibling tools, but the precondition framing leaves little ambiguity about when this applies.

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