Fuul MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.12.0
Disambiguation4/5
Most tools have clearly distinct purposes, with detailed descriptions that help differentiate them. However, the large number of tools related to referrals and affiliates could cause some confusion for an agent.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern in snake_case, such as list_chains, create_trigger, and approve_payouts. No mixed conventions are observed.
Tool Count3/5
39 tools is on the higher side for a single server, covering a broad API surface. While the complexity of the domain may justify the count, it risks overwhelming agents and could benefit from splitting into sub-servers.
Completeness4/5
The tool set covers CRUD operations for most entities and includes essential workflows like event tracking and payouts. However, the absence of a 'publish' operation (noted as required externally) is a notable gap.
Average 4.3/5 across 39 of 39 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 71 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It indicates a PATCH mutation, but does not mention side effects, authorization requirements, reversibility, or any destructive behavior. The reference to approve_payouts is insufficient to fill this gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence), but it is too sparse to be considered well-structured. It front-loads the action, but lacks essential details that could be included without adding verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, low schema coverage, no output schema, no annotations), this description is severely incomplete. The agent cannot reliably invoke this tool based on the provided information alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no meaning to the 8 parameters beyond what the input schema provides. Schema description coverage is only 38%, and the description does not compensate by explaining key parameters like dry_run, confirmed, or date filters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Rejects payouts' and provides the HTTP endpoint, distinguishing itself from the sibling 'approve_payouts' by referencing its body rules. However, it lacks additional detail about what rejection entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'approve_payouts'. The description only mentions 'Same body rules as approve_payouts', which refers to parameter structure, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description discloses several behavioral aspects: it is a GET operation, requires a dashboard JWT, returns scoped counts, and includes rate limit handling (HTTP 429 with Retry-After). However, it does not explicitly state idempotency, safety (read-only), or potential side effects, which are important for a GET tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of four sentences plus an example and a retry note. It is front-loaded with the core purpose and endpoint, then adds essential details (auth, UI mapping, rate limits). The inline example is helpful but slightly disrupts flow; overall, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 7 parameters, the description covers key points (endpoint, response fields, auth, rate limits, example) but omits explanations for most parameters and the full response structure. For a tool with moderate complexity, it is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29%, and the description adds minimal parameter semantics. The example illustrates project_id and user_identifier format, but the other five parameters (from, to, this_month, conversion_external_id, conversion_name) are not explained in the description. The schema’s own descriptions for user_identifier and this_month are present but insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as retrieving affiliate stats for one user identifier, mentioning the endpoint path and the specific response fields (active_referred_users_r2–r4). While it distinguishes itself from sibling tools by focusing on individual stats, it does not explicitly contrast with similar tools like get_project_affiliates_breakdown, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. It mentions that query params match the dashboard UI, implying a specific use case, but lacks when-not-to-use instructions or comparisons with sibling tools. The rate limiting advice is helpful but not sufficient for usage guidelines.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the endpoint, auth requirements, and dry_run/confirmed flow, which is helpful. However, with no annotations, it omits details like response format, error handling, and idempotency, leaving gaps for a complex mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise single paragraph front-loads purpose then packs body fields, auth, and pattern. Every sentence adds value without redundancy. Could be slightly more structured (e.g., bullet points) but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 13 complex parameters, the description covers the endpoint, auth, body structure, and execution pattern adequately. It addresses major concerns for a creation tool, though missing return value info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (23%), but description adds context for many parameters (e.g., dry_run, confirmed, user_identifier_type, and the approve/review pattern). Still, several fields like region, status, note lack elaboration, so the description only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it creates a managed project affiliate via POST, listing the endpoint and body fields. While it doesn't explicitly differentiate from siblings like create_incentive, the verb+resource combination is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides important auth guidance (only project API key, not OAuth) and the dry_run/confirmed pattern. However, it lacks explicit when-to-use versus alternative create tools, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses HTTP method, endpoint structure, and includes a retry hint for HTTP 429. Since no annotations are provided, this adds useful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus an example and retry hint. Front-loaded with key information, no superfluous content. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers basic endpoint, filters, and retry behavior, but lacks details on response format, default behavior, and differentiation from similar tools (e.g., get_affiliate_portal_stats). No output schema increases the need for more contextual description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Lists filter names and provides an example JSON, but does not fully define each parameter's meaning or constraints. With 0% schema description coverage, the description offers some compensation but not comprehensive semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Aggregated project-wide affiliate totals' and provides the endpoint path, indicating a specific verb (GET) and resource. However, it does not explicitly differentiate from sibling tools like get_affiliate_portal_stats or get_project_affiliates_breakdown.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_affiliate_portal_stats or get_project_affiliates_breakdown. Missing context on typical use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the read-only nature (calls two GET endpoints) and the merge logic. Discloses that published_conversion_id is null for now. However, missing details on error handling, rate limits, or required permissions. With no annotations, the description carries the burden but is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose. It efficiently conveys the structure and merge behavior. Minor technical jargon could be simplified, but overall well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with no output schema, the description covers the return fields (slug, draft_conversion_id, published_conversion_id, draft, published, triggers) and the merge process. It provides an example. While it could mention pagination or sorting, it is fairly complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (project_id) is well-documented in the schema with format and description. The tool description adds an example but does not provide additional semantics beyond the schema. Baseline score of 3 is appropriate due to full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists draft incentives with merged published trigger IDs, specifies the HTTP endpoints, and details the structure of each item (slug, draft_conversion_id, etc.). It distinguishes from siblings like get_incentive and create_incentive by providing specific merge behavior and field definitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. Does not mention prerequisites, limitations, or when not to use it. Sibling tools are listed but not compared.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description includes endpoint and optional parameters but does not describe response structure, pagination behavior, or authentication requirements. As a list operation, missing output schema is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus example. Efficiently conveys purpose and key parameter fields without extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 6 parameters and no output schema, description omits response format, pagination details, error handling, and required permissions. Incomplete for a tool with moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. Description only repeats parameter names without explaining semantics like acceptable status values or date formats. Example provides context for two parameters but insufficient for all six.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists rewards payouts history and provides the endpoint path. Distinguishes from related sibling tools by specifying 'history' vs pending payouts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Lists optional parameters but does not specify when to use this tool over alternatives like list_payouts_pending_approval. No explicit exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose all behavioral traits. It mentions the endpoint and parameter constraints (mutual exclusivity, two-step flow) but does not describe error handling, side effects, rate limits, or what happens when confirmed is false. The description is insufficient for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the purpose, then provides the endpoint, parameter constraints, and an example. It is front-loaded and efficient, with no extraneous information. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters and no output schema, the description covers the core logic (mutual exclusivity, two-step) and includes an example. However, it lacks details on return values, error scenarios, and the exact behavior of the confirmed parameter. Completeness is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (38%), so the description must add meaning. It clarifies that payout_ids and from_date/to_date are mutually exclusive on the server, and that dry_run must be done before confirmed. It also provides an example JSON. However, it omits user_address and affiliate_address parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Approves payouts' and includes the HTTP endpoint PATCH /api/v1/projects/:projectId/payouts/approve. It specifies the key parameters (payout_ids or date filters) and the two-step process (dry_run then confirmed). This distinguishes it from sibling tools like reject_payouts and list_payouts_pending_approval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a sequential process: run dry_run first, then confirmed. However, it does not explicitly state when to use this tool over alternatives (e.g., reject_payouts) or provide prerequisites or authorization hints. Usage context is somewhat clear but lacks thorough guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description implies read-only operation via 'Lists' and mentions HTTP GET endpoint, but does not explicitly state idempotency, auth requirements, or pagination behavior beyond optional params. With no annotations, it provides moderate disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose and endpoint, second explains optional parameters with examples. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is present, and description does not explain return format (e.g., array of projects, pagination metadata). For a list tool, this omission leaves the agent uncertain about expected response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. Description adds examples and clarifies that page is 1-based, which supplements schema's exclusiveMinimum. This adds meaningful usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Lists dashboard projects for the current user', indicating the verb (list), resource (dashboard projects), and scope (current user). It differentiates from siblings like get_project by focusing on listing multiple projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., get_project for a single project, or list_incentives for incentives). Lacks explicit context for selective invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility. It successfully discloses the two-step process (dry_run then confirmed) and the clearing behavior of audience_id. It does not cover authorization needs or error conditions, but the core mutation behavior is well explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus a helpful example. Every sentence earns its place, and the information is front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no output schema, and no annotations, the description covers the essential workflow and parameters. However, it does not describe the return value, error scenarios, or how to construct required fields project_id and tier_id. This leaves some gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, so the description must compensate. It explains that audience_id null clears the audience and that at least one optional field is required. This adds value beyond the schema, but it does not elaborate on other parameters like name or rank beyond their existence. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a project affiliate tier and provides the HTTP method and path. It lists the optional fields and the workflow (dry_run then confirmed). While it does not explicitly differentiate from sibling update tools, the resource and fields are specific enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the dry_run/confirmed pattern and the requirement of at least one optional field. However, it does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Specifies GET method (idempotent), required and optional parameters, and rate limit behavior ('wait Retry-After seconds'). Does not mention authentication or destructive actions, but as a GET it's safe.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with purpose, then parameter list, example, and rate limit note. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complex tool with 11 parameters and no output schema. Description explains input parameters and rate limits but does not describe return values, error responses (beyond 429), or what the breakdown actually contains (e.g., metrics, format). Significant gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description compensates partially. Lists optional parameters (sortBy, sortOrder, date filters, dimension filters) and provides an example with project_id, groupBy, dateRange. However, does not explain meaning of each parameter beyond enum values (e.g., sortBy options are metrics).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Affiliate breakdown for a project' with specific grouping options (audience, tier, region, status). Distinguishes from sibling tools like get_affiliate_portal_stats and get_project_affiliate_total_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly declares required parameter groupBy and lists optional parameters. Provides an example and includes rate limit handling advice (HTTP 429). However, lacks explicit when-to-use vs alternatives and exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the two-phase dry_run/confirmed workflow and provides an example, adding meaningful behavioral context beyond the schema. No annotations exist to contradict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: purpose+endpoint, Dto field summary, workflow with example. No wasted words, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately covers parameters and workflow for the tool's complexity (8 params, two-phase commit). Lacks return value description but no output schema exists. Reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite low schema coverage (38%), the description maps to most parameters, explains condition_match_mode requirement when conditions non-empty, and illustrates the dry_run/confirmed order. This compensates for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an audience (user list), provides the HTTP PATCH endpoint, and differentiates from sibling update tools targeting other resources like triggers or project tiers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., other update tools); lacks when-not-to-use or prerequisites like requiring an existing audience.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It clarifies that the tool returns a draft incentive, and provides specific details about the conversion_id being a draft UUID and how trigger IDs are used. It implies read-only behavior but does not explicitly state no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences plus an example, conveying key information efficiently. It packs in details about trigger IDs, but could be slightly more structured. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with two parameters and no output schema, the description provides sufficient context: what the tool does, parameter semantics, and an example. It does not cover return format, but that is acceptable given no output schema. It feels complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only conversion_id has schema description). The description adds meaning by clarifying conversion_id is a 'draft conversion UUID from incentives API' and provides an example. This compensates for the missing project_id description and adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Tool explicitly states it 'Gets one draft incentive with scoped triggers', using a specific verb and resource. It distinguishes itself from list_incentives by mentioning 'same merge' and provides context about draft vs published trigger IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need a single draft incentive and its associated trigger IDs, but lacks explicit when-to-use or when-not-to-use guidance compared to siblings like get_trigger or list_incentives. The hint about using draft_trigger_id for PATCH update_trigger is helpful but not a full guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries burden. It discloses the HTTP method (GET) and pagination, but doesn't mention behavior like empty results, rate limits, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences plus an example. Front-loaded with purpose, no fluff, well-structured for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 does not explain return values or pagination metadata. For a list tool, this information is important for agent planning.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 2 of 3 parameters with descriptions (page, page_size). The description adds an example showing how to use project_id and pagination, providing practical context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists payouts pending approval and provides the REST endpoint, distinguishing it from sibling tools like approve_payouts and reject_payouts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description specifies optional pagination parameters, implying usage for retrieving pending payouts. While it doesn't explicitly state when not to use it, the context of sibling tools makes the purpose clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool performs a partial update, requires dry_run then confirmation, and uses project API key auth. It also mentions clearing tier_protection with null. No side effects or rate limits are noted, but the update nature is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but packs essential information: endpoint, fields, auth, workflow, and an example. It is front-loaded and each sentence adds value. Slightly verbose due to the example but justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 parameters, no output schema), the description covers authentication, workflow, partial update, and a dry_run example. It lacks response details and deep parameter descriptions, but for an update tool it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%), but the description adds meaning for several parameters (e.g., 'tier_protection including null to clear', 'approve_project_tier_ids with reviewed_by_user_id'). However, some parameters like 'audiences' and 'region' are listed without additional context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Updates a managed project affiliate' and provides the exact endpoint URL, making the operation clear and specific. It lists the updatable fields, distinguishing it from related tools like create_project_affiliate_public.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the authentication requirement (project API key only, not OAuth) and the dry_run-before-confirmed workflow. However, it does not explicitly state when to use this tool versus alternatives like creating or fetching affiliates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It mentions the authentication requirement and provides an example, but does not detail potential error responses or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences and an example. It front-loads the core purpose and includes essential usage context without unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema), the description covers the necessary context: what it does, what it returns, and the prerequisite. An explanation of error handling for unauthenticated users would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the schema is fully covered. The description adds meaning by specifying the return value (user info) and providing an example, which is appropriate for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns the current Fuul dashboard user as JSON, specifying the exact verb and resource. It distinguishes itself from sibling tools by focusing on identity retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the prerequisite of prior CLI login, providing context for when to use the tool. However, it does not explicitly state when not to use it or mention alternatives among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description discloses auth restrictions (project API key only), null field behavior, and that it reflects PUT assignments. Lacks mention of rate limits or pagination, but sufficient for a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Packed with useful info (path, return fields, comparison, auth, example) but could be slightly trimmed. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return fields, auth, example, and comparison despite no output schema and low schema coverage. Completeness is adequate for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only project_api_key described), but description adds meaning through example and explanation of fallback for project_api_key and enumeration of user_identifier_type, compensating for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it reads a user referrer, includes HTTP method and path, and differentiates from sibling tool by explaining the difference in behavior with referral_code_uses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context by comparing to another endpoint and specifying auth requirements, but does not explicitly list when not to use it or other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the transparency burden. It discloses the multi-step, stateful behavior (statuses: listed_use_same_address, needs_user_input, resolved) and provides examples. It could be more explicit about error conditions or what happens if invalid parameters are passed, but overall it is quite transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (~120 words) and well-organized with enumerated steps and examples. Every sentence adds distinct value, no redundancy. It is front-loaded with the purpose, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the step-by-step usage and parameter conditions well. However, it does not describe the response format or output structure (e.g., exact fields returned for each status). Given the absence of an output schema, this gap makes the tool harder to integrate without external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 adds significant value by explaining the conditional roles of parameters: token_kind and decimals are only needed when status is 'needs_user_input'. Concrete JSON examples further clarify usage beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves 'context.volume_currency_expression for token-holder triggers' and outlines a specific three-step process. It distinguishes itself from siblings like 'list_price_references' by focusing on a single token's resolution path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides step-by-step instructions on when to pass which parameters (e.g., first call with token_address, second with token_kind/decimals if needed). It also warns about create_trigger rejecting unlisted tokens when using token_address directly. However, it does not explicitly list when not to use the tool or name alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It details parallel API calls, trigger row structure, stable key behavior, publish effects, and conversion handling. This is comprehensive behavioral disclosure beyond basic read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and provides detailed but relevant information in a single paragraph. It could be slightly more concise by splitting into sentences, but each part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description thoroughly explains the return structure, including trigger mapping, key stability, and conversions. It covers complex behaviors and edge cases, making it complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'project_id' described as 'Project UUID'. The description adds no additional semantic meaning beyond the schema, but the overall context explains how the parameter is used in API calls. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Loads one project (draft + published trigger mapping)' which is a clear verb+resource combination. It mentions specific API calls and distinguishes from siblings like 'list_projects' by specifying it loads a single project with trigger mapping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for loading a single project, which differentiates from list tools. However, it does not explicitly state when to use this tool versus alternatives, or provide exclusions. The context of sibling tools suggests appropriateness, but no direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool returns whichever row (draft or published) and does not resolve metadata_id, and gives an example. However, it does not mention authentication requirements or potential errors, which would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, three sentences long, with the core purpose in the first sentence. Every sentence provides necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool, the description covers the return behavior (draft vs published), a key limitation (no metadata_id resolution), and provides an example. Lacks mention of error handling or output schema, but the context is sufficient for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema describes project_id as uuid and trigger_id as uuid with description 'Trigger UUID'. The tool description adds context about the endpoint and provides an example with both UUIDs. With 50% schema coverage, the description adds some value but does not deeply elaborate on parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a trigger row by UUID, specifies the HTTP method and endpoint, and distinguishes that it returns either draft or published copy. It also provides differentiation from sibling tools by suggesting alternatives for draft_trigger_id vs published_trigger_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains that the tool does not resolve project.metadata_id and suggests using get_project or get_incentive with triggers[] instead for related lookups. This gives clear when-to-use and 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses caching, output structure (enums, reward_types, create_payload_example), and links to webapp mappers. While it doesn't explicitly state read-only or side-effect-free, the listing nature and GET path imply it. The detail compensates for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is dense but well-structured: front-loads purpose, then lists output details. Every sentence adds value. Could be slightly more structured with bullet points, but overall efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description provides extensive context: cached data, enums, reward types with examples, and a top-level payload guide. It fully prepares the agent for what to expect and how to use the output with create_incentive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters; schema coverage is 100%. Baseline for 0 params is 4. The description adds substantial value by detailing the output structure, going beyond schema requirements. It compensates for the lack of parameters by explaining what the tool returns in depth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists payout schema metadata from a specific API endpoint, enriches it for create_incentive, and enumerates detailed contents. It distinguishes itself from siblings like list_incentives and list_chains by specifying its purpose and linkage to create_incentive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Call before create_incentive,' providing a clear when-to-use directive. It does not enumerate when not to use or alternatives, but the context and explanation of enrichment for create_incentive imply its specific role. The caching mention hints at staleness considerations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses side effects: refreshes project metadata, resolves stale UUIDs, returns _draft_id_resolution and _publish_metadata_reminder, and does not publish. Does not mention potential destructive aspects on already-used terms.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Reasonably concise given complexity; front-loaded with purpose and endpoint. Some redundancy (e.g., repeating endpoint later) but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers ID resolution, dry_run flow, error handling, and publish reminder. Lacks explicit details on success response structure (e.g., updated payout term fields), but adequate for a complex tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond schema: explains payout_term should be full payload from get_incentive, clarifies variable reward fields, maps GET aliases, and explains dry_run/confirmed usage. Schema coverage 67% but description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates one payout term on a draft conversion, providing the API endpoint and distinguishing it from siblings like create_incentive and delete_incentive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides detailed guidance on variable vs per-unit rewards, dry_run, confirmed flag, and ID resolution. However, lacks explicit 'when not to use' or comparisons to all sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: full detail response, authentication requirements, and endpoint pattern. It does not cover rate limits or error handling but sufficiently describes the tool's operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with a third line for the example, all essential. It is front-loaded with the core function, then auth, then example. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains what the response contains (tiers, protections, audiences, tax). It covers auth, endpoint, and parameter usage. The tool is simple with no nested objects, so the description is sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (project_api_key described, project_affiliate_id only format). The description adds an example and clarifies auth fallback, adding value beyond the schema. However, it does not detail the UUID parameter's purpose beyond the tool's function.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it loads one managed project affiliate with full details including tiers, protections, audiences, and tax. It specifies the HTTP method and endpoint. This distinguishes it from siblings like get_project_affiliates_breakdown which likely provides aggregated data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (loading a single managed affiliate) and provides critical authentication guidelines (only project API key, not dashboard OAuth). It lacks explicit exclusions or comparisons to alternative tools but gives clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description discloses it makes no API calls and returns 'pong'. Sufficient for a trivial read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with zero waste, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple health check; no output schema needed as return is trivial. No gaps given tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, schema coverage 100%, and baseline for 0 params is 4. Description correctly says invoke with empty input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it's a health check that returns 'pong' if running, with no API calls. Distinct from siblings as it's a simple connectivity test.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says no API calls and to use empty input, indicating when to invoke. Does not compare with sibling 'whoami', but purpose is straightforward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses atomicity, silent duplicate ignoring, response structure (ingested_events count), auth requirements (project API key only, not OAuth), rate limit (10 req/min), and Retry-After handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is lengthy but well-structured with sections and code examples. Front-loaded with key details. Could be slightly more concise but remains clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (batch, atomic, auth, rate limiter, dry_run), the description covers all essential aspects. No output schema, but response description (ingested_events count) is provided. Adequate for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value by explaining dry_run/confirmed workflow, auth fallback, and args structure for value/revenue, going beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb ('send'), resource ('up to 100 conversion events'), and HTTP endpoint. It distinguishes from sibling send_event by emphasizing batch and atomic processing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('for backfills and bulk ingestion') and mentions dry_run then confirmed workflow. However, it does not explicitly state when not to use (e.g., for single events where send_event is more appropriate).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses side effects: refreshes project metadata, resolves IDs, remaps published IDs, and includes response fields like _draft_id_resolution and _publish_metadata_reminder. States that MCP cannot publish.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Despite length, every sentence adds value. The description is well-structured, starting with purpose, then API, usage pattern, and detailed behavior. Not overly verbose given complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensively covers all aspects: delete semantics, ID resolution, dry_run behavior, post-execution notes, and MCP limitations. No gaps for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% but description adds meaning: explains dry_run/confirmed workflow, specifies that conversion_id is the draft UUID from list_incentives, and clarifies required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it deletes a draft incentive, provides the API endpoint, and distinguishes from sibling tools like delete_conversion and delete_trigger.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes the dry_run then confirmed pattern and when to use delete_conversion before delete_trigger in a replace flow. Offers clear but not exhaustive usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, description thoroughly explains behavior: uses server metadata, caching mechanism, field details (snake_case, specific fields, boolean semantics), and pagination limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured and front-loaded, but includes extra details (e.g., field descriptions) that add value yet slightly reduce conciseness; still acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all relevant aspects: source, caching, field semantics, pagination limitations. Adequate for a simple list tool without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, schema coverage 100%; description confirms no params needed. Baseline 4 is appropriate as no additional meaning is necessary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists supported blockchain chains from a specific API endpoint, differentiating from sibling tools that focus on payouts, incentives, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on how it works (server metadata, caching) and that no parameters are needed, but does not explicitly contrast with alternative tools since no competitors exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: atomicity, non-idempotency (with safe retry mapping), authentication method, and the dry-run/confirm pattern. This exceeds expectations for transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it starts with purpose, then details atomicity, authentication, error handling, and workflow. Each sentence adds unique value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers authentication, error handling, workflow, and atomicity. However, it does not describe the success response format (e.g., what a successful removal returns), which would be helpful given the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is 63%, the description adds significant context by explaining the dry_run/confirmed workflow and providing a comprehensive example. It also clarifies the project_api_key fallback behavior. The example illustrates all parameters in context, compensating for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Remove a user from a referral code') and details the atomic database operations (deletes user_referrers and referral_code_uses, decrements actual_uses). It clearly distinguishes from sibling tools like 'delete_user_referrer' by specifying the exact endpoint and behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear instructions on when to use the tool, including authentication requirements (only project API key, not OAuth) and the dry-run-then-confirm workflow. It also explains error handling for 422 cases. However, it does not explicitly differentiate from similar sibling tools like 'swap_user_referral_code'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. Discloses two endpoints based on verbose flag, parameter combinations, auth method (project API key only, no OAuth), rate limit of 100/min, retry-after behavior, and response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded purpose, but slightly verbose. All information is necessary, though could be tightened. Still highly readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 7 parameters, description covers all parameter combinations, auth, rate limits, error handling, polling advice, and examples. Extremely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
71% schema coverage but description adds critical context: explains dependency of verbose on event_id or dedup_id+event_name, clarifies user_identifier fields for non-verbose, and provides examples. Adds significant meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Check event ingestion and downstream pipeline', distinguishes between verbose/non-verbose modes, and specifies API endpoints and required parameters. This distinguishes it from sibling tools like send_event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit polling guidance after send_event, parameter requirements, authentication (project API key only), rate limits, and error handling (404/429). Lacks explicit 'when not to use' but context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description comprehensively covers behavioral traits: what it clears/destroys, what it does not touch, error handling (422 mapping), auth restrictions (service_role key only, not OAuth), and the dry_run/confirmed workflow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured with front-loaded main action. It efficiently communicates endpoint, workflow, error handling, and auth. Every sentence adds necessary detail, though could be slightly tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains error handling and idempotent behavior well. It covers dry_run/confirmed workflow and auth. Lacks explicit success response structure, but overall sufficiently complete for a deletion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60%, but the description adds value by providing an example dry_run, explaining the workflow for dry_run and confirmed, and clarifying the user_identifier fields. This compensates for the lack of schema descriptions on two parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Remove admin-imported user_referrers row' and includes the HTTP endpoint. It distinguishes from sibling 'remove_user_from_referral_code' by specifying when to use that alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (removing imported referrer) and when not to use (if user has referral code redemptions, use sibling). Also provides guidance on idempotent retry mapping and auth requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the data is cached, enriched for create_trigger, and details the response structure including fields like context_json_schema and create_payload_layout. No annotations are provided, so the description carries the full burden, and it does so adequately, though it could mention caching freshness 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it begins with the main purpose, explains the enriched data, and ends with a clear usage instruction. Every sentence adds value without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description provides complete context: it explains the source (cached API), the enriched response structure, and the usage instruction. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and schema description coverage is 100%. The description correctly notes 'Params: {}', adding no further parameter information since none is needed. Baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists trigger type metadata from a specific API endpoint, enriched for create_trigger. It specifies the resource and verb, and distinguishes it from siblings by indicating it is a prerequisite for create_trigger.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Always call this before create_trigger.' This provides clear usage guidance on when to use the tool, making it obvious that it is a prerequisite step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although no annotations exist, the description fully covers behavioral traits: it explains the API call, optional filtering, result structure, and crucial behavioral consequence that a wrong reference leads to a trigger that never prices correctly. It also clarifies no destructive actions and sets expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but well-structured: it starts with the core purpose, then adds filtering, result format, workflow, and examples. Every sentence serves a purpose, though some could be slightly compressed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains what results contain (identifier, name, decimals, chain_identifier). It also provides a complete workflow, prerequisites, and error examples. The tool's role as a prerequisite is clearly established, and all necessary information for correct invocation is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, and the description adds value by providing examples of usage ('ethereum'), referencing where the chain_identifier comes from (list_chains), and illustrating both with and without the parameter. This goes beyond the bare schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists currencies usable as price references for token-holder triggers, specifies the API endpoint, and explains its role as a prerequisite for create_trigger. It distinguishes itself from related tools by providing workflow context, and the detailed examples enhance clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when the tool is required (before create_trigger when token is unknown), provides a step-by-step workflow, includes concrete examples of correct and incorrect usage, and warns about consequences of wrong references. It implicitly advises when to use alternatives (if token is known).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers non-atomicity, partial failure responses (partial:true), authentication requirements (project API key only), error handling (422 tolerance), and dry_run pattern. Contradiction: false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded with the core verb and outcome. Every sentence adds value, though it could be structured with bullet points for easier parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers response format (partial:true, use_error/use_referral_code), edge cases (legacy users, first assign), auth method, and dry_run workflow—comprehensive for a complex mutation tool without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds critical context beyond the schema, e.g., explaining step 2 assigns to to_referral_code owner and clarifying project_api_key fallback. Schema coverage is 56%, and the description partially compensates by embedding parameter meanings in the narrative.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Move a user between referral codes' and details the two-step process (DELETE then PATCH), distinguishing it from siblings like use_referral_code and remove_user_from_referral_code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use alternatives: 'For first assign with no prior code, use use_referral_code directly.' Also instructs to clear legacy blockers with delete_user_referrer, providing clear when-to-use and 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description fully covers behavioral traits: immutable fields, metadata refresh, ID remapping, error handling, and publish reminder. It also explains the replace flow steps and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely informative with no wasted sentences. It is front-loaded with the main action, then provides guidelines and replacement flow. Could be slightly more concise, but every part serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 19 parameters, many siblings, and no output schema, the description covers all critical aspects: main action, immutability constraints, replacement flow, dry_run/confirmed pattern, ID remapping, and publish reminder. It is complete for correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 16%, but the description lists allowed update fields (name, description, event_type, expressions, payable, ref, contract_ids) and clarifies immutability of others. This adds significant meaning beyond the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it updates a trigger via PATCH, lists allowed fields, and contrasts with immutable context fields. It distinguishes itself from create_trigger and delete_trigger by specifying that context changes require a replace flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidelines: when to use (updating mutable fields), when not to (changing token/chain), and a detailed replacement flow. Also instructs to use dry_run then confirmed and to list linked conversions before deleting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description thoroughly discloses idempotent upsert, side effects (no creation of referral_code_uses), auth requirements (service_role project API key only), and flow steps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
5-6 sentences, each providing distinct value: action, idempotency, side-effect disclaimer, alternative, auth, and a concrete example. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the essential aspects: action, flow, auth, and an example. Lacks details on response/error schema but overall sufficient given the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 4/8 parameters with descriptions. Description provides context for project_api_key (env variable fallback) and an example covering identifier parameters, compensating for the remaining half.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it creates or overwrites user_referrers via idempotent upsert, and distinguishes from sibling use_referral_code by noting it does not create referral_code_uses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (admin override) and when to use alternative (use_referral_code for real code redemption). Also explains required auth and dry_run/confirmed flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even without annotations, the description fully discloses side effects (creates referral_code_uses, increments actual_uses, sets user_referrers), idempotency behavior under service_role, and auth constraints (no Dashboard OAuth, no wallet signature with service_role). This exceeds minimum transparency requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense and front-loaded with the core action, but it contains some technical jargon and could be streamlined slightly. Nevertheless, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description thoroughly explains return behavior (referral status endpoint), acknowledges the two-step commit pattern, covers auth, and mentions idempotency. It fully addresses the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the input schema covers 4 of 6 parameters with descriptions, the tool description adds critical context for referral_code (owner is referrer) and explains the dry_run/confirmed workflow. However, user_identifier and user_identifier_type are not elaborated beyond the schema example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Redeem a referral code for a user') and includes the HTTP endpoint. This verb+resource structure effectively distinguishes it from siblings like remove_user_from_referral_code or swap_user_referral_code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly specifies when to use the tool (user has no existing referrer) and when not (user already has referrer unless service_role replay). It also clarifies authentication requirements (project API key only) and the dry_run-then-confirm pattern, providing clear decision-making context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries behavioral disclosure. It explains that the tool performs a mutation (creates draft), refreshes project metadata, resolves trigger IDs to current draft UUIDs, returns error for stale IDs, and includes _publish_metadata_reminder on success. It also notes that the MCP cannot publish for the user, making side effects transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured: core purpose first, then step-by-step guidance. Every section adds value, though some details about payout schemes could be condensed for even better conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, nested payout_terms, no output schema), the description covers all key aspects: prerequisites, ID resolution, dry_run workflow, error handling, and post-execution reminders. It is fully complete for confident agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema, especially for payout_terms where it details scheme types, field mappings, and normalization rules. It also clarifies ID resolution for trigger_ids and the purpose of dry_run/confirmed. Schema coverage is 67%, but the description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a draft incentive via a specific API endpoint, and distinguishes it from sibling tools like create_trigger by detailing prerequisite steps (list_payout_schemas first) and the required workflow (dry_run then confirmed).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit prerequisites: 'REQUIRED: list_payout_schemas first—pick reward_types[].id and use create_payload_example.' Also explains when to use dry_run before confirmed, and that the tool refreshes project metadata and resolves IDs. This gives clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses draft creation (no mutation until confirmed), that using unlisted token gives HTTP 201 but broken runtime, and that response includes publish reminder. Mentions MCP cannot publish. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very detailed but slightly verbose; could be more concise. However, well-organized with examples and bullet points. Content justifies length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return value (publish reminder) and critical caveats. Covers pre-requisites and failure modes. Exceptionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds substantial meaning beyond schema: explains trigger object layouts based on type, provides examples for token-holder and custom, and clarifies dry_run and confirmed roles. Schema coverage is 75% but description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it creates a draft trigger with POST endpoint. Distinguishes from siblings like update_trigger and delete_trigger via detailed instructions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call list_trigger_types first, use trigger_types[].id, follow create_payload_layout, call list_chains, and use dry_run then confirmed. Also provides specific guidance for token-holder price references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses two-phase commit, ID remapping, metadata refresh, response elements (_draft_id_resolution, _publish_metadata_reminder), and error handling (HTTP 422 guidance).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Lengthy but well-structured: front-loaded with main action, then step-by-step flow, behavior, and response details. Every sentence is valuable, but could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary context: no output schema, but describes response fields, error handling, preconditions, and post-execution actions. No gaps left for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: explains dry_run/confirmed behavior, trigger_id accepts draft or published IDs (with remapping), and project_id context from the API path. Compensates for missing schema description on project_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Deletes a draft trigger' with HTTP method and path. Distinguishes from siblings like delete_incentive by specifying that it handles draft and published trigger IDs with remapping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (only after dry_run and confirmed, never without user approval), when not to use (if incentives still link), and provides a detailed replace-trigger flow with steps and alternative tools like update_trigger.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: idempotency via dedup_id (409), dry_run/confirmed workflow, rate limiting (429 with Retry-After), auth requirements (only project API key), and detailed args shape for value/revenue. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized, with essential info first (purpose, required fields, dedup behavior, auth, rate limits) and detailed args later. Could be slightly trimmed, but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 params, nested objects, no output schema), the description covers auth, errors, rate limits, workflow, and args thoroughly. It also directs to check_event_status for verification, completing the usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 89%, and the description adds significant context beyond the schema: explains the dry_run/confirmed workflow, details the args.value/revenue structure with examples, and clarifies auth parameter fallback. This enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send one conversion event' and provides the endpoint. It distinguishes from sibling tools like send_batch_events and check_event_status, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use this tool (after dry_run/confirmed pattern), when to use alternatives (check_event_status for verification), and when not to use (auth specifics: Dashboard OAuth not accepted). Also covers rate limits and error handling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![mcp_server MCP server](https://glama.ai/mcp/servers/kuyen-labs/mcp_server/badges/card.svg)](https://glama.ai/mcp/servers/kuyen-labs/mcp_server)

Score Badge

Copy to your README.md:

[![mcp_server MCP server](https://glama.ai/mcp/servers/kuyen-labs/mcp_server/badges/score.svg)](https://glama.ai/mcp/servers/kuyen-labs/mcp_server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kuyen-labs/mcp_server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server