AudD MCP is a way for agents to add music recognition to apps or to fulfill song identification requests. It connects you to AudD, the music recognition API
Scored across 20 tools
Tools are mostly distinct with clear purposes, but there is some overlap between make_api_request and recognize_song_from_url for music recognition, and among get_account_status, get_usage_stats, and get_amount_owed for account usage/billing. Descriptions are detailed enough to guide selection, so ambiguity is low but not zero.
All tools use consistent snake_case verb_noun or verb_noun_phrase naming. No deviations or mixed conventions, making the pattern predictable and easy to follow.
20 tools is slightly above the ideal range but appropriate for a full-featured music recognition API covering recognition, stream management, billing, account, and API access. Each tool appears to earn its place, though some consolidation could reduce count.
Core workflows for recognition, stream lifecycle, billing, and account management are covered. Missing direct file-upload recognition (explicitly not supported via make_api_request) and a way to update account settings like auto-renew, which are minor gaps agents can work around.
Use this only when the user asks to start monitoring a radio or live stream. AudD then recognizes the stream continuously and sends results to the callback URL: by default after each song ends, or as soon as a song starts with callbacks="before" (those results have no play length). radio_id is the user's own integer for the stream and must be unique on the account. The account's streams plan needs a free stream slot.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Stream URL (Icecast, HLS, DASH, m3u/m3u8, ...) or a shortcut: twitch:<channel name>, youtube:<video id>, youtube-ch:<channel id> | |
| radio_id | Yes | Any integer that will identify this stream, unique on the account | |
| callbacks | No | Optional: "before" sends results when a song starts instead of when it ends |
| Name | Required | Description |
|---|---|---|
| added | Yes | |
| radio_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a non-read-only, non-idempotent, open-world write, so the bar is lower, yet the description adds substantial context: continuous recognition behavior, default callback timing (after each song ends), the callbacks="before" mode and its lack of play length, plus the uniqueness and plan-slot constraints. This is real operational detail an agent cannot get from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The usage directive is front-loaded and the sentences largely earn their place. Slight redundancy in restating radio_id's uniqueness, which the schema already carries, keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with an output schema (so return values need not be described), the description covers purpose, trigger condition, callback semantics, and a plan-slot prerequisite. It omits what happens on a duplicate radio_id and any auth/rate-limit notes, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, and the schema already documents url, radio_id, and the callbacks enum. The description adds value beyond it by explaining that callbacks="before" results "have no play length" and re-emphasizing the account-unique constraint on radio_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ("Add a stream") and scopes it precisely to "continuous recognition" of a radio/live stream. The word "continuously" cleanly separates it from the one-off sibling recognize_song_from_url, so an agent can route without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use this only when the user asks to start monitoring a radio or live stream" is an explicit when-to-use directive with an implicit exclusion of single-song recognition. It also names a precondition ("The account's streams plan needs a free stream slot"), though it never explicitly names a sibling alternative for one-off lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a Stripe-backed payment link for buying N extra API requests (multiples of 1000). The link must be opened and approved by the account owner in a browser - this tool never charges a card by itself.
| Name | Required | Description | Default |
|---|---|---|---|
| requests | Yes | Number of requests, multiple of 1000 |
| Name | Required | Description |
|---|---|---|
| requests | No | |
| payment_url | Yes | |
| amount_cents | Yes | |
| human_approval_required | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the generic mutation profile (readOnlyHint=false, idempotentHint=false). The description adds genuinely new behavioral facts: the charge is handled by Stripe, the tool never charges a card itself, and purchase requires an out-of-band browser approval by the account owner. That is exactly the context an agent needs before calling a payment tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with zero filler; the core action is front-loaded and the clarifying constraint about browser approval follows immediately. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return-value details are unnecessary, and the description covers the mechanics of the purchase well. It is slightly thin on idempotency behavior (calling twice to create multiple links) given idempotentHint=false, but nothing critical to correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter already documents 'Number of requests, multiple of 1000' with matching min/max bounds. The description restates the multiple-of-1000 constraint but adds no semantics beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Creates a Stripe-backed payment link') plus the scope of what is being bought ('N extra API requests, multiples of 1000'). This is clearly distinguishable from siblings like create_renewal_payment and subscribe_to_plan, which handle different billing flows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by explaining the flow (link must be opened and approved by the account owner in a browser), but it never states when to choose this over subscribe_to_plan or create_renewal_payment, nor any preconditions such as having usage overages. Guidance is inferable but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a Stripe-backed payment link to renew the subscription (including any owed extras). The link must be opened and approved by the account owner in a browser - this tool never charges a card by itself.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| payment_url | Yes | |
| amount_cents | Yes | |
| includes_extras_cents | No | |
| human_approval_required | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the safety profile (not read-only, not destructive, not idempotent). The description adds genuinely new behavioral context: the tool never charges a card itself and the link must be opened and approved by the account owner in a browser. It does not address the non-idempotent behavior (whether repeated calls mint multiple links), which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste, and the most important constraint (the tool does not charge by itself) is front-loaded after the purpose. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need not be explained, and the description covers purpose and the approval flow. The main residual gap is lifecycle behavior after the link is generated or whether calls accumulate links, but for a zero-parameter tool this is close to complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema has nothing to document and the baseline of 4 applies. There is no parameter semantics the description could usefully add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('Creates') plus resource ('Stripe-backed payment link to renew the subscription'), with the scope of what the link covers ('including any owed extras'). An agent can distinguish this from subscribe_to_plan, buy_bonus_requests, and get_amount_owed without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The renewal scenario is implied and the browser-approval workflow gives context, but no sibling is named and there is no explicit when-to-use-this-vs-subscribe_to_plan or get_amount_owed guidance. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this only when the user asks to stop monitoring a stream. AudD stops recognizing it and removes it from the account; this cannot be undone (add the stream again to resume).
| Name | Required | Description | Default |
|---|---|---|---|
| radio_id | Yes | The integer that identifies the stream on this account (see list_streams) |
| Name | Required | Description |
|---|---|---|
| deleted | Yes | |
| radio_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds real value: the operation is irreversible ('this cannot be undone'), the stream is removed from the account, and the recovery path is stated (add it again to resume). That is meaningful behavioral context beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the usage constraint is front-loaded and the consequence/recovery is second. No filler, no repetition of the title, and every clause carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, and annotations cover the safety profile. Combined with the irreversibility warning and the resume path, the description is nearly complete for a one-parameter destructive tool; only explicit framing of the delete-vs-update choice among siblings is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter with 100% schema coverage, and the schema already explains radio_id and points to list_streams for discovery. The description adds no syntax, format, or ID-resolution detail beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource ('stop monitoring a stream') and details the concrete effect: AudD stops recognizing it and removes it from the account. It is clearly distinguishable from siblings like list_streams, add_stream, and update_stream_url, though it never names an alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The opening clause 'Use this only when the user asks to stop monitoring a stream' gives an explicit trigger plus an implicit exclusion ('only'), which is strong when-to-use guidance. It stops short of naming alternatives (e.g., update_stream_url for changing rather than removing) or stating preconditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current AudD plan, subscription status (active, trial, lapsed, lapsed_settled, banned), paid-until date, bonus requests, and auto-renew setting.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| plan | No | |
| status | Yes | |
| paid_till | No | |
| auto_renew | Yes | |
| bonus_requests | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds genuine domain context by enumerating the possible subscription status values (active, trial, lapsed, lapsed_settled, banned), which tells the agent what state space to expect. It does not mention rate limits or refresh/caching behavior, so it is not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence with no filler, and the most important element (the current plan) is front-loaded. It is a noun fragment rather than a sentence, which is acceptable for a compact field enumeration but slightly weakens the structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description is not obliged to document return values, yet it usefully summarizes them; with zero parameters and full read-only annotations, nothing required to invoke the tool is missing. The only gap is the absence of routing guidance versus get_profile/get_billing_history.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to clarify beyond the already-complete schema coverage, and it does not need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description enumerates exactly what the tool returns — plan, subscription status, paid-until date, bonus requests, auto-renew — which clearly separates it from siblings like get_profile or get_billing_history. It never states a verb (e.g. 'retrieve the account's billing/plan status'), so the purpose is inferred from the noun list rather than declared, keeping it short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use statement, and no sibling is named as an alternative. Usage is only implied by the field list: an agent can infer it is the tool to call when it needs plan/subscription/auto-renew state. That is adequate for a zero-argument status getter but leaves the choice against get_profile and get_amount_owed to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Settle-aware calculation of over-allowance usage accrued this cycle and the amount (in cents) it will cost at the next renewal or settle.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| note | No | |
| allowance | No | |
| owed_requests | Yes | |
| used_this_cycle | No | |
| owed_amount_cents | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, idempotent, non-destructive profile. The description adds useful behavioral context by specifying the calculation basis (over-allowance usage this cycle) and the timing (cost at next renewal or settle) and currency (cents).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It is dense but appropriately sized for the tool's simple signature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations cover safety, the description is nearly complete. It explains the calculation and timing, though it omits any usage guidance or sibling differentiation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4. There are no parameters whose meaning could be clarified in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific calculation: over-allowance usage accrued this cycle and its cost at renewal or settle. It is clear what the tool computes, but it does not explicitly distinguish this from siblings like get_usage_stats or get_billing_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. The description only explains what is calculated, with no context about when this is the appropriate choice over get_billing_history or get_usage_stats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the official AudD API documentation (markdown). Topics: "api" (main endpoint: recognition, parameters), "streams" (continuous stream recognition and stream management), "enterprise", "file-upload".
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | api |
| Name | Required | Description |
|---|---|---|
| topic | Yes | |
| documentation_markdown | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the return is static markdown documentation, and it summarizes what each topic contains. It stops short of noting anything about caching, auth, or freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with what is returned before the topic list. Every clause carries information; nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only documentation fetch with a single optional enum parameter and an output schema that already describes the return shape, the description is nearly complete. Only the absence of explicit usage framing keeps it from being fully sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the load. It does: each enum value is given meaning ('api' = main endpoint with recognition and parameters, 'streams' = continuous recognition and management, plus 'enterprise' and 'file-upload'), which is genuinely more than the bare enum names in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Returns the official AudD API documentation') and specifies the format (markdown). It is unmistakably distinct from the account/billing siblings (get_account_status, get_amount_owed, etc.), so an agent can select it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the nature of the tool (fetch docs to learn about the API), but there is no explicit when-to-use statement, no guidance such as 'call this before configuring streams' or 'use to look up parameters,' and no exclusions. Adequate but leaves routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the account api_token used to call api.audd.io. This is the preferred way to build an integration: save the token and call the API directly from your script rather than proxying each call through make_api_request. Sensitive: only available when the user granted the token:read scope.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| api_token | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=true, which alone would leave an agent unsure what the tool actually does; the description resolves this by clarifying it is a credential-retrieval operation and adds two things annotations cannot convey: it is sensitive and it requires the user to have granted the token:read scope. It does not describe failure behavior when the scope is missing, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the return value, then the recommended usage pattern, then the authorization caveat. No sentence is redundant and the ordering matches how an agent decides to call it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description needn't explain the returned payload, and it already covers the two things an agent must know before invoking: the scope requirement and why direct API calls are preferred. Nothing material is missing for a zero-parameter retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly avoids inventing argument semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb and resource ('Returns the account api_token used to call api.audd.io'), which unambiguously separates it from siblings like make_api_request and rotate_api_token. An agent can identify exactly what the tool yields without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly routes the agent: use this to build an integration and call the API directly rather than proxying each call through make_api_request. That names the alternative tool and the condition that selects this one, which is the strongest form of usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent payments on the account: subscriptions, renewals, extra-request settles, bonus purchases; amount, paid status, dates.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many records (default 20) |
| Name | Required | Description |
|---|---|---|
| payments | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a read-only, idempotent, non-destructive operation, so the safety burden is lifted. The description adds useful context about which payment categories appear in the result, but says nothing about ordering, the time span covered by 'recent', or what happens when the limit is reached.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence with the resource and result contents front-loaded and no filler. It is a sentence fragment rather than prose, but nothing in it is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations covering the safety profile, an output schema documenting returns, and a single optional parameter fully described in the schema, the description supplies everything an agent needs to select and call this tool. Restating 'amount, paid status, dates' is redundant against the output schema but not harmful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single limit parameter already documents its meaning and default of 20. The description adds no parameter-level guidance beyond that, so the baseline 3 for schema-complete definitions applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (recent payments on the account) and enumerates the record types it covers: subscriptions, renewals, extra-request settles, bonus purchases. It is distinguishable from balance-oriented siblings like get_amount_owed, but never names or contrasts with an alternative, so it stops short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use statement, no indication of when this is preferable to get_amount_owed or get_account_status, and no mention of the time window that 'recent' implies. Usage is only inferable from the phrase 'Recent payments'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The account email address and the connected sign-in methods (Google, GitHub, email, Telegram, ...).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| No | ||
| user_id | Yes | |
| sign_in_methods | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered elsewhere. The description adds only the scope of disclosed data (email and sign-in providers), with no note on auth requirements, caching, or staleness — acceptable given the annotation coverage, but nothing beyond it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that names the two pieces of data returned and gives concrete examples of providers. Not a word wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description is not obliged to explain return values, and rich annotations cover behavior; the only real gap is the absence of any routing guidance relative to sibling read tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter semantics for the description to carry; the baseline for a 0-param tool is 4. Schema coverage is 100% and there is nothing further to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource precisely — account email plus connected sign-in providers — which clearly distinguishes it from siblings like get_account_status, get_amount_owed, and get_billing_history. It lacks an explicit verb ('returns'), but the noun phrase plus the get_profile name leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, and no mention of any alternative or overlapping sibling. An agent must infer from the name alone that this is the right call versus get_account_status or get_usage_stats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks where AudD sends their stream recognition results. Returns the account's callback URL, or null when AudD reports that none is set (a temporary AudD error can look the same, so confirm with the user before replacing it). Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| callback_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered; the description adds real value beyond that by disclosing the null-return case and the important nuance that a temporary AudD error can be indistinguishable from 'no callback set'. That ambiguity warning is exactly the kind of behavioral context structured fields cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the usage trigger followed by the return/caveat behavior. The trailing 'Read-only.' is mildly redundant given readOnlyHint=true, a small amount of dead weight against otherwise efficient prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read with an output schema present, the description supplies everything an agent needs: when to call it, what it returns, the null case, and the error-ambiguity caveat. Return-value structure is properly left to the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and the schema declares additionalProperties=false, so there is nothing to disambiguate; the baseline for a parameterless tool is 4. No parameter-level guidance is needed or missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource ('Returns the account's callback URL') and frames it in user-intent terms ('when the user asks where AudD sends their stream recognition results'). It is clearly distinguishable from the sibling setter set_stream_callback_url, which the 'before replacing it' clause implicitly separates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states an explicit trigger condition tied to user intent, and adds a genuine caution about confirming with the user before acting on a null result. It stops short of naming the alternative tool (set_stream_callback_url) for the replacement path, so the routing is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
API usage statistics (aggregate daily request counts only): current billing-cycle total, allowance, remaining, and per-day counts. Optional "days" returns the last N days instead of the current cycle.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Return daily stats for the last N days instead of the current billing cycle |
| Name | Required | Description |
|---|---|---|
| daily | Yes | |
| allowance | Yes | |
| cycle_end | No | |
| remaining | Yes | |
| cycle_start | No | |
| used_this_cycle | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered; the description adds the meaningful boundary that only aggregate daily counts are available (no per-endpoint breakdown). It does not address stats freshness or any delay between usage and reporting, which is the main remaining behavioral unknown for a usage-stats tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the scope restriction and the returned fields, then the parameter note. Zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With rich annotations, an output schema documenting return shape, and one fully described optional parameter, the description covers what an agent needs. The only gap is data freshness/latency, minor given the rest of the structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and there is a single optional parameter already fully documented with bounds (1-366) in the schema. The description restates the same semantics ('last N days instead of the current cycle') without adding format or edge-case detail, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and scope: 'API usage statistics (aggregate daily request counts only)' with the fields returned (cycle total, allowance, remaining, per-day). The 'aggregate daily request counts only' qualifier implicitly separates it from per-request history tools like get_billing_history, but no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is about the optional 'days' parameter ('returns the last N days instead of the current cycle'), which describes parameter behavior rather than when to choose this tool. Nothing tells the agent when to prefer get_usage_stats over get_amount_owed or get_billing_history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The publicly available AudD subscription plans with pricing and included requests. Use the "plan" value with subscribe_to_plan.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| plans | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is fully covered. The description adds the useful fact that only public (non-account-scoped) plans are returned and that pricing/request counts are included, but says nothing about auth requirements or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler: the first defines the resource and payload, the second routes the agent to the consuming tool. Front-loaded and fully earned.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value documentation is not required, and the description covers scope and payload. It stops short of noting that this listing is unauthenticated/public, which would be the last useful behavioral detail for an agent deciding whether it can call it in a bare context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The mention of a 'plan' value refers to output consumed by subscribe_to_plan, not to an input parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the exact resource ('publicly available AudD subscription plans') and the payload ('pricing and included requests'), so an agent knows precisely what comes back. The 'publicly available' qualifier implicitly separates it from account-scoped siblings like get_billing_history or get_account_status, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence gives a concrete downstream usage rule — feed the 'plan' value into subscribe_to_plan — which is genuinely actionable context. However, it never states when to call this tool versus the billing siblings, nor any prerequisites, so guidance is implied rather than enumerated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks which radio or live streams their account monitors with AudD stream recognition. Returns each stream's radio_id, its URL, and whether recognition is currently running. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| streams | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description reinforces 'Read-only' and adds the returned fields, but does not disclose anything beyond what annotations already provide, and the return details are in the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences that front-load the trigger and then summarize the return. The trailing 'Read-only' is redundant with the annotations, but the description is otherwise economical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, zero-parameter read-only listing tool with rich annotations and an output schema, the description provides everything needed: when to call it, what it returns, and its safe read nature. No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there are no parameter semantics to document. The baseline for a zero-parameter tool is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (list monitored streams), scopes it to the user's account and AudD recognition, and names the returned fields. This clearly distinguishes it from siblings like add_stream, delete_stream, and update_stream_url.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use it when the user asks which streams their account monitors. Clear triggering context, though it does not mention alternative tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calls the AudD API (api.audd.io) as this account - music recognition, streams management, callbacks, etc. Uses the account plan quota exactly like a direct API call. For repeated or programmatic use, PREFER get_api_token and call https://api.audd.io/ directly from your own code/script - that is more efficient and reliable than routing every call through this tool; use make_api_request for one-off or interactive calls. Read get_api_docs first for endpoints and parameters. Audio must be passed by URL (e.g. params.url); binary file upload is not possible through this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | API path, default the main endpoint "/". E.g. "setCallbackUrl" | / |
| params | Yes | Request parameters as key-value strings, e.g. {"url": "https://example.com/a.mp3", "return": "spotify,apple_music"} (api_token is added automatically) |
| Name | Required | Description |
|---|---|---|
| error | No | |
| result | No | endpoint-specific result payload (object, array, or null) |
| status | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, openWorldHint=true, and non-idempotence, so the safety profile is largely covered. The description adds genuine context beyond them: it consumes the account plan quota exactly like a direct API call, and it cannot accept binary file uploads (audio must be a URL). It does not spell out which calls are destructive or how errors/rejections surface, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with what the tool is and what it costs, then the alternative-tool guidance, then prerequisites, then a hard limitation. It is dense but every sentence carries operational information; the mid-sentence em-dash list and slightly long quota/preference clause keep it from a perfect 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic pass-through API tool with an output schema available, the description covers the essentials an agent would otherwise guess wrong: authentication context ('as this account'), quota consumption, the preferred alternative path, the docs prerequisite, and the no-file-upload constraint. Nothing critical is left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so path and params are already documented in the schema, including the api_token injection note. The description adds only the constraint that audio must arrive via a URL-style param (e.g. params.url) rather than a file upload, which is useful but marginal over the structured fields; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete verb plus resource ('Calls the AudD API (api.audd.io) as this account') and enumerates the capability surface (music recognition, streams management, callbacks). It also names the sibling tools it relates to (get_api_token, get_api_docs), so an agent can place it against 19 alternatives without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit routing guidance: prefer get_api_token for repeated or programmatic use and call the API directly, and reserve make_api_request for one-off or interactive calls. It also states a prerequisite ('Read get_api_docs first for endpoints and parameters'), which is exactly the when-to-use info an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to know which song is in an audio or video file at a public URL (a direct link to the file, such as an .mp3). Only the first 12 seconds of the audio are analyzed, so it returns at most one song. Returns the artist, title, album, release date, label and a song link, plus optional links to the track on Apple Music, Spotify, Deezer or MusicBrainz. Each call counts against the account's request quota, like a direct API call, and a retry counts again; on paid plans, requests beyond the plan's included allowance are billed at the plan's rate at the end of the billing period. Do not use for lyrics or to find several songs in a long recording.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public http(s) URL of the audio or video file | |
| market | No | Optional two-letter country code for Apple Music and Spotify results (default us) | |
| return | No | Optional services to include links for |
| Name | Required | Description |
|---|---|---|
| song | Yes | |
| matched | Yes | false when the audio was processed but no song matched |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide generic hints (readOnlyHint=false, openWorldHint=true). The description adds substantial non-obvious behavior: only the first 12 seconds are analyzed, at most one song is returned, each call consumes quota, retries count again, and overage is billed on paid plans. This goes well beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary use case, then constraints, then billing implications, then exclusions. Every sentence carries distinct decision-relevant information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-shot recognition tool with full schema coverage, an output schema, and rich annotation context, the description covers when to use it, the analysis limit, quota/billing behavior, and the output contents. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents url, market, and return (including the default 'us' and the enum of services). The description restates the public-URL requirement and the service links but adds no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('which song is in an audio or video file at a public URL') and clearly distinguishes this from the sibling tools, which are all account/stream/billing management. An agent can identify the function without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit positive guidance ('Use this when the user wants to know which song is in an audio or video file at a public URL') and explicit exclusions ('Do not use for lyrics or to find several songs in a long recording'). Both the trigger condition and the anti-patterns are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replaces the account api_token with a new one and returns it. The OLD TOKEN STOPS WORKING IMMEDIATELY - only call this when the user explicitly asks to rotate/revoke their token.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| rotated | Yes | |
| api_token | Yes | |
| callback_url_status | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds the crucial consequence that the OLD TOKEN STOPS WORKING IMMEDIATELY and that the new token is returned. This specifies exactly what is destroyed and when, which is richer than the boolean hint alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The destructive consequence is front-loaded and the usage restriction follows, giving the highest-risk information first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need no explanation, and the empty parameter set means there is no input to document. The description covers the destructive effect and the usage trigger completely for a parameterless mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. No indication of any implicit input is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Replaces the account api_token with a new one') and distinguishes itself from the sibling get_api_token by describing replacement rather than retrieval. An agent can tell exactly what this does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call it ('only call this when the user explicitly asks to rotate/revoke their token'), which functions as both a usage condition and a guardrail against autonomous invocation. No inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this only when the user asks to set or change the URL where AudD sends stream recognition results and stream notifications. It replaces the account's current callback URL; results for all of the account's streams go to the new URL from then on.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public http(s) URL that will receive the results |
| Name | Required | Description |
|---|---|---|
| updated | Yes | |
| callback_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare mutation semantics (readOnlyHint=false, destructiveHint=true, idempotentHint=true), and the description adds context those annotations cannot convey: the existing callback URL is replaced outright and the change applies to all of the account's streams going forward. That replacement/scope behavior is exactly the kind of state-change disclosure an agent needs, though no auth or permission requirements are mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the gating condition and then the state-change semantics, with no redundant restatement of the name or title. Every clause carries information an agent needs at call time.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the destructive/idempotent annotations plus the description's replacement semantics cover the mutation risk profile. The only gap is the absence of any authentication or permission prerequisite for changing an account-wide setting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter is already documented as 'Public http(s) URL that will receive the results', so the schema carries the burden. The description adds marginal value by noting the URL also receives stream notifications, but contributes no format or validation detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb (set/change) and resource (the account's stream recognition-results callback URL), so an agent knows exactly what is being configured. It also clarifies scope (account-wide, replacing the current URL) which distinguishes it from a per-stream update or the getter sibling, though it never names get_stream_callback_url explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this only when the user asks to set or change the URL...' provides an explicit gating condition and an implied exclusion for other cases. It stops short of naming the alternative tool (get_stream_callback_url) or stating when not to use it beyond 'only when the user asks'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a Stripe-backed payment link to subscribe to (or switch to) a plan from list_plans. The link must be opened and approved by the account owner in a browser - this tool never charges a card by itself.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | Yes | Plan identifier from list_plans (e.g. indie_plan_outside, startup_plan, pro_plan) |
| Name | Required | Description |
|---|---|---|
| payment_url | Yes | |
| amount_cents | Yes | |
| human_approval_required | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this as non-read-only, non-destructive and non-idempotent; the description adds valuable context beyond them by clarifying that no card is charged directly and that owner browser approval is required. It does not, however, mention that repeated invocations create separate links (relevant given idempotentHint=false) or any auth/permission expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no waste; the core action is front-loaded and the important constraint (no charge without browser approval) follows immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. For a one-parameter tool, the description covers origin of the plan ID, the human-approval flow, and the no-charge guarantee — nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there is a single required parameter, so the schema already carries the parameter meaning. The phrase 'from list_plans' reinforces the plan identifier's source but adds no syntax or format detail beyond the schema, matching the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb (creates) and resource (a Stripe-backed payment link) for subscribing to or switching plans, and anchors the 'plan' value to the sibling tool list_plans. An agent can distinguish it from buy_bonus_requests or create_renewal_payment without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It makes clear the intended flow: the link must be opened and approved by the account owner in a browser, and the tool never charges a card itself. That is strong usage context, but it does not explicitly state when to prefer this over the payment-related siblings (e.g., buy_bonus_requests vs create_renewal_payment).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this only when the user asks to change the URL of a stream they already monitor. It replaces that stream's URL; recognition continues on the new URL under the same radio_id.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Stream URL (Icecast, HLS, DASH, m3u/m3u8, ...) or a shortcut: twitch:<channel name>, youtube:<video id>, youtube-ch:<channel id> | |
| radio_id | Yes | The integer that identifies the stream on this account (see list_streams) |
| Name | Required | Description |
|---|---|---|
| updated | Yes | |
| radio_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose the safety profile (destructiveHint=true, idempotentHint=true, openWorldHint=true), so the bar is lower. The description adds genuinely useful context beyond them: the old URL is replaced and recognition persists on the new URL under the same radio_id, which tells the agent the stream identity is preserved rather than recreated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the usage constraint is front-loaded and the behavioral consequence follows. No filler, and every clause carries information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation with full schema coverage, an output schema (returns needn't be described), and annotations covering mutability and idempotency, the description covers usage and effect adequately. Minor gaps remain around the fate of the previous URL and any prerequisite state, but nothing critical to correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both radio_id and url are already documented (including URL formats and twitch:/youtube: shortcuts). The description ties them together by noting the URL is replaced while radio_id is retained, but adds no syntax or format detail beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (change a stream's URL) and pins the scope to a stream the user 'already monitor[s]', which implicitly separates it from add_stream and delete_stream. The second sentence clarifies what 'change' means operationally (URL swapped, recognition continues under the same radio_id).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Use this only when the user asks to change the URL of a stream they already monitor' gives a clear triggering condition and an implicit exclusion (not for creating or removing streams). It stops short of naming the alternative sibling tool (add_stream) explicitly, so it lacks the full when-not/alternative routing of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
add_streamdelete_streamget_account_status2 fields changedOutput schema / properties / plan / propertiesAdded value: +{
+ "extra_price_cents_per_1000": {
+ "type": "integer"
+ },
+ "id": {
+ "type": "integer"
+ },
+ "included_requests": {
+ "type": "integer"
+ },
+ "monthly_price_cents": {
+ "type": "integer"
+ },
+ "name": {
+ "type": "string"
+ }
+}Output schema / properties / status / enumAdded value: +[
+ "active",
+ "trial",
+ "lapsed",
+ "lapsed_settled",
+ "banned"
+]get_billing_history1 field changedOutput schema / properties / payments / items / propertiesAdded value: +{
+ "amount_cents": {
+ "type": "integer"
+ },
+ "billing_month": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "bonus_requests_granted": {
+ "type": "integer"
+ },
+ "created_at": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "extra_requests_billed": {
+ "type": "integer"
+ },
+ "id": {
+ "type": "integer"
+ },
+ "kind": {
+ "type": "string"
+ },
+ "paid": {
+ "type": "boolean"
+ },
+ "paid_at": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+}get_stream_callback_urllist_streamsrecognize_song_from_urlrotate_api_token1 field changedOutput schema / properties / callback_url_statusAdded value: +{
+ "type": "string"
+}set_stream_callback_urlupdate_stream_urlbuy_bonus_requestscreate_renewal_paymentget_api_tokenmake_api_requestrotate_api_tokensubscribe_to_planget_account_statusget_amount_owedget_api_docsget_billing_historyget_profileget_usage_statslist_plans
Add one secure layer between your agents and this server.