Koddeo

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

Annotations already declare non-readonly, open-world, non-idempotent, non-destructive. The description adds real value beyond them: the side effect is deferred behind an external payment step, and the boost only starts after payment succeeds. It doesn't warn that repeated calls create multiple checkouts, though idempotentHint=false implies 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?

Three compact sentences, front-loaded with the action, followed by price options and the payment-link behavior. No 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 two-parameter tool with no output schema and full annotation coverage, the description covers purpose, outcome, pricing, and activation timing. Only minor gaps remain, such as link expiry or whether the code must already be published.

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 only 50% — the duration enum has no description. The description compensates by mapping each duration value to its price and period (48h €0.79, 1 week €1.49, 3 weeks €2.99), giving the agent the meaning of the unlabeled enum. The code_id parameter is already documented in 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?

States a specific verb and outcome: create a Stripe checkout to pin a user's code to the top of its brand page. 'Boost' vs publish_code/list_my_codes is clearly separable from the description alone.

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?

Describes the full flow — create checkout, user opens the returned link to pay, boost activates on payment success — which tells the agent what to do with the result. It stops short of explicit when-not conditions or naming siblings like subscribe_premium as an alternative.

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, so safety is covered. The description adds real behavioral context the annotations do not: only 'active' codes are returned and results follow the Koddeo page order with boosted and Premium codes first. It stops short of disclosing pagination or how many codes come back by default.

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 with zero filler; the scope and ordering rule are stated up front.

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 read-only list tool this covers purpose and ordering, but leaves the result-size behavior unexplained: an agent cannot tell from the description that it gets only 5 codes by default or that 20 is the cap. That is the one material gap given there is no 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 coverage is only 50%: slug is well documented, but limit (default 5, max 20) has no description in the schema and is never mentioned in the description. The ordering sentence adds nothing about the limit parameter, so the description does not compensate for the coverage gap.

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 (List) and resource (active community referral codes for one brand) plus the ordering semantics. It distinguishes itself implicitly from list_my_codes by scoping to 'one brand', but never names a sibling or says how it differs from list_my_codes/get_my_account.

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?

Usage is only implied: use it when you want a brand's codes. There is no explicit 'use this when', no exclusions, and no pointer to alternatives such as list_my_codes for the caller's own codes. The slug schema field does point to search_companies, which partially routes the agent.

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, so safety and scope are covered structurally. The description contributes the 'connected user' scoping (no user id needed) and hints at the returned content, but says nothing about freshness, authentication requirements, or error behavior.

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 short sentence with zero filler, and the key scoping fact (connected user) is front-loaded. It reads as a fragment rather than a sentence with a verb, which slightly weakens actionability.

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 parameterless read with no output schema, the description does the essential job by listing the three returned data points. It stops short of describing format or limits (e.g., what 'daily refresh quota' values look like), which would have made it fully self-sufficient.

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 per the baseline this is a 4; the description correctly implies no input is needed by tying the result to 'the connected user'.

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 the resource ('the connected user's account') and enumerates the concrete fields returned: plan, daily refresh quota, published codes count. It is clearly distinguishable from siblings like get_company_codes and list_my_codes, though it is written as a noun phrase with no explicit verb ('returns' / 'retrieves').

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?

There is no indication of when to call this versus alternatives such as list_my_codes or get_company_codes, and no mention of prerequisites like authentication. Usage is only inferable from the fact that it takes no parameters.

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, so the safety profile is covered. The description adds useful context by naming returned metrics and Boost status, but it does not mention ordering, pagination, or authentication requirements.

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 a single compact noun phrase with no wasted words. It is front-loaded with the resource and scope, though it lacks a complete sentence structure that might improve readability.

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-parameter read-only list tool, the description gives enough context about what is returned: referral codes with views, clicks, and Boost status. With no output schema, it could say more about return ordering or completeness, but the essentials are present.

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 has zero parameters, so there are no parameter semantics to document. Baseline 4 is appropriate because the schema is empty and no additional parameter meaning is needed.

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 identifies a specific resource: the connected user's referral codes, along with returned metrics (views, clicks, Boost status). It distinguishes personal codes from the sibling get_company_codes, though it does not use an explicit verb like '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?

There is no explicit guidance on when to use this tool versus get_company_codes, boost_code, or refresh_code. The word 'my' implies personal scope, but alternatives and exclusions are left to inference.

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=false, destructiveHint=false, idempotentHint=false, so the safety profile is known. The description usefully adds the uniqueness rule implying conflicts will fail, but says nothing about required permissions, what a duplicate attempt returns, or whether re-publishing updates an existing listing.

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, front-loaded with the action and target, then the constraint, then the parameter rule. No filler or restated schema text.

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 non-idempotent mutation with five parameters and no output schema, the description covers the core action and uniqueness rule but omits error/conflict behavior and what the call produces. Enough to call it, not enough to call it confidently.

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 parameters are already documented; the description still adds real value by clarifying that code and link are alternatives (at least one required) even though neither is in the required list. It stops short of explaining how title and description interact with the published card.

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 ('Publish one of the user's referral codes') plus the target surface ('on a brand page'), which is concrete and actionable. It doesn't differentiate itself from close siblings like boost_code or refresh_code, so an agent must infer the boundary.

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?

'One code per brand per user' gives an important usage constraint, and 'Provide a code, a referral link, or both' tells the agent how to satisfy the input. But there is no explicit guidance on when to publish versus boost/refresh an existing code, leaving sibling selection to inference.

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 is a non-idempotent, non-destructive mutation. The description adds real value beyond them with the per-day quota and Paris-time reset window, which an agent cannot infer from the schema. It omits what happens to existing/old codes after a refresh and what occurs when the quota is exceeded.

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, zero waste, with the action front-loaded and the constraint in the second sentence. Every clause 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 zero-parameter action tool with annotations and no output schema, the description covers action, scope, and quota. The main remaining gap is the side effect on previously issued codes, which matters for a non-idempotent bulk 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it correctly avoids inventing inputs.

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 with explicit bulk scope: 'bump every active code of the user at once'. The 'every ... at once' phrasing implicitly distinguishes it from the sibling refresh_code, though it never names that sibling.

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 quota sentence implies when the tool is available ('1 per day' vs 'unlimited'), which is useful gating context. However, it never says when to prefer this over refresh_code or list_my_codes, and gives no explicit when-not-to-use guidance.

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 is a non-destructive, idempotent, closed-world mutation, so the safety profile is covered. The description usefully adds the effect—restoring ranking position on the brand page rather than creating a new boost—which is not in the annotations. However it stays silent on cost/credits, cooldowns, limits on how often a code can be refreshed, or what happens when the code is already at the top, all of which matter for a ranking-affecting write.

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 short sentence with the action front-loaded and no filler. It is efficient, though the brevity comes partly at the cost of the missing guidance noted elsewhere.

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 a crowded sibling set (boost_code, refresh_all_codes, publish_code), the definition should say what the operation returns or what distinguishes it from boost_code. Neither is present, so it is not complete enough for confident selection.

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 the single parameter's description already tells the agent to source code_id from list_my_codes. The description adds no syntax, format, or constraint detail 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?

The sentence names a verb ("bump ... back up") and a resource (a code) and scopes the effect to the brand page ranking, which is concrete. But "bump back up" is vague about the actual mechanism, and it gives no signal distinguishing it from the sibling boost_code, which reads as an almost identical operation—nor from refresh_all_codes. An agent must guess which of the three to call.

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?

There is no statement of when to use this rather than boost_code or refresh_all_codes, no prerequisites, and no exclusions. The only usage hint comes indirectly from the code_id schema note pointing at list_my_codes.

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, so safety is covered; the description adds the meaningful behavioral constraint that results are filtered to brands that actually have community referral codes, and discloses a returned field (slug). It does not describe match semantics (exact vs partial/keyword ranking) or what an empty result looks like.

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: the first defines the resource and scope, the second the return value and its downstream use. Front-loaded and 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?

With no output schema, the description partially compensates by naming the returned slug field, and it explains the domain filter. It leaves a small gap on result-set size/limit behavior and matching semantics, which matters because limit is undocumented in the 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 coverage is 50%: query is documented with examples in the schema, while limit has no description at all. The description's category examples (banks, crypto, delivery, VPN) loosely reinforce the query's keyword nature, but it says nothing about limit's default of 8 / max of 20 or about search matching behavior. Baseline 3 for a half-documented two-parameter 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?

Specific verb (Search) plus resource (brands listed on Koddeo), with concrete category examples and the explicit constraint that only brands with community referral codes are returned. It also names the sibling tools it feeds into (get_company_codes, publish_code), so an agent can distinguish it from the code-retrieval tools 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?

The description tells the agent this is the discovery step whose output (the slug) is then used with get_company_codes or publish_code, giving a clear workflow context. It stops short of explicit when-not guidance, e.g. that it is not for listing codes directly or what to do on zero results.

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 declare non-read-only, open-world, non-idempotent, non-destructive, but the description adds the crucial behavioral fact that the call returns a link the user must open to actually pay — i.e., no charge happens here — plus the already-subscribed fallback to the billing portal. It stops short of covering link expiry, failure modes, or auth requirements.

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 clauses: what it creates, what it returns, and the already-subscribed edge case. Front-loaded with the action and pricing, 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?

With no output schema, the description correctly explains the return value (a payment link, or a billing portal link). For a payment flow it could still mention auth requirements or what happens if the Stripe call fails, but everything needed to invoke it correctly is present.

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 0%, so the description must carry the parameter meaning, and it does: it ties the two pricing options (€5.99/month vs €47.88/year) to the MONTHLY/YEARLY enum, letting the agent infer which plan value to send. It doesn't discuss the YEARLY default or how plan affects anything else.

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+resource (create a Stripe checkout for Koddeo Premium) and enumerates the exact benefits and prices. No sibling tool touches subscriptions, and the description makes that boundary obvious.

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?

States the outcome when the user is already subscribed (returns the billing portal), which tells the agent this tool is safe to call regardless of current state. It does not state explicit prerequisites such as being logged in, but with no competing subscription tool there is little ambiguity about when to use it.

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