Dynamoi

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

With annotations only declaring readOnly/idiompotent/destructive/openWorld hints, the description adds substantial flow context: this records an application for manual review, downstream country/tax/payout/sanctions/provider-delivery checks remain manual progression gates, and a valid code does not imply approval. This goes well beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose, then exclusions, then hard requirements, then downstream gates, then idempotency. Every clause earns its place; the density reflects genuinely load-bearing constraints rather than 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?

An output schema exists so return values need not be explained, and the description fully covers the high-complexity concerns an agent needs: preconditions, required inputs, manual-review nature, and idempotency. It is complete for a mutating, gate-heavy application 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?

Schema description coverage is 0%, so the description must carry the burden, and it does: it clarifies that all three country fields are valid ISO 3166-1 alpha-2 codes, that adult signer attestation and confirmApplicationSubmission=true are required, and that userIntentSummary should be concise. It leaves artistId implicit, which is a minor gap given the obvious resource reference.

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 ('Submit an artist's application for Dynamoi music distribution') and immediately delimits scope against adjacent actions (approving, accepting agreements, submitting releases, transferring rights, configuring splits/tax, delivering to stores). An agent can clearly distinguish this from get_distribution_application and other siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit preconditions ('after the user explicitly asks to apply and all five eligibility requirements are met') and explicit non-goals ('it does not approve distribution, accept an agreement, submit a release...'). It also notes idempotent behavior on repeat submission, so the agent knows when re-invoking is safe. Nothing important is left to inference.

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

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

Beyond the annotations, it discloses the verification-hold behavior for high-popularity or unverifiable artists, the free-to-create cost model, the idempotent dedup rule (return the existing link rather than a duplicate), and the side effect that customDescription mutates an existing Smart Link's public description. The dedup and update behaviors go well past what readOnlyHint/destructiveHint/idempotentHint convey.

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 definition is dense but front-loaded: purpose first, alternatives and exclusions next, then edge cases and output guidance. The opening two sentences overlap ('Use this for "make a link for my song"' vs 'Use this when the user wants to create one free Dynamoi Smart Link'), which is the only real waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is rightly omitted, and the description still covers the critical edge cases (dedup, verification hold, unsupported inputs) plus how to present the result. The only gap is silence on three non-required parameters and the format enum, which leaves the agent guessing about output shape selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning, and it only partially does: spotifyUrl's accepted resource types and customDescription's dual create/update role are explained, but artistId, format, clientRequestId, and userIntentSummary are never mentioned. Useful but incomplete against a 6-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource (create one free Smart Link) and immediately scopes it to Spotify album/track URLs or a single starter release from an artist URL. It explicitly distinguishes itself from dynamoi_create_smart_links_from_spotify_artist, so an agent can route between the two without reading either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states when to use it ('make a link for my song'), when to prefer the sibling for full-catalog imports, and hard exclusions (Spotify playlist URLs unsupported, does not create a paid ad campaign). It also covers the less obvious 'add a missing release' path, which is genuine routing guidance.

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

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

Annotations already declare write/idempotent/non-destructive, and the description usefully adds behavior beyond them: it starts a background catalog import, links may sit in a verification hold for high-popularity or unverifiable artists, and creation/management is free. It does not explain idempotency semantics for clientRequestId or any auth/rate-limit constraints.

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 when-to-use condition is front-loaded and each sentence carries distinct information (trigger, artistId branch, async import, verification hold, cost, scope exclusion, output guidance). It runs slightly long at six-plus sentences, but there is little outright 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?

An output schema exists, so return values need not be re-explained, and the description covers the required parameter and key edge cases. But for a 5-parameter, 0%-schema-coverage tool it leaves four parameters undefined and never resolves the overlap with the singular sibling create tool, which is the most likely mis-selection risk.

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% across 5 parameters, so the description carries the full burden, yet it only explains artistId (omit it to let Dynamoi create the first artist). clientRequestId, format (enum json/summary), and userIntentSummary are never mentioned, and spotifyArtistUrl is only implied by the trigger sentence.

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 concrete verb+resource ('create, import, or refresh free Smart Links for the artist catalog and return the artist hub'), which is far more specific than the title alone. However, it never distinguishes itself from the near-identical sibling 'dynamoi_create_smart_link_from_spotify' (singular), leaving the agent to infer catalog-vs-single-link scope on its own.

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 an explicit trigger ('when the user gives a Spotify artist URL') plus a conditional branch for the no-artist case (omit artistId) and an exclusion ('does not create a paid ad campaign'). It stops short of naming the alternative sibling tool, so routing between the singular and plural create tools is left implicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: account-level state can span multiple artists, which is exactly why it should not be used to confirm a single onboarding attempt. Output format is not described, but an output schema exists to carry that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The routing information is front-loaded and useful, but the sentence is long and enumerates a broad list of musician intents ('promote a new single, check how a release is doing, make a song link...') that overlaps with the later prohibition on generic questions. Some of this text could be trimmed without loss, and the lead-in slightly dilutes the account-scoped purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter, read-only lookup with an output schema covering return values, the description is nearly complete: it establishes purpose, routing, and the multi-artist scope caveat. The only remaining gap is the unexplained 'format' parameter, which is minor given the self-describing enum.

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 compensate, and it partially does: it explains that 'intent' should match the explicit account question and that it defaults to account_overview, adding meaning beyond the enum list. The 'format' parameter (json/summary) receives no explanation at all, leaving that choice to inference from the enum values alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (the signed-in Dynamoi account) and enumerates concrete scope items it covers: who is logged in, how many organizations/artists are accessible, and whether account-level platform connections exist. It clearly distinguishes itself from siblings like dynamoi_list_artists and dynamoi_get_platform_status. The opening 'start here when a musician asks...' hook is slightly broad and in mild tension with the later narrowing, but the core purpose is unambiguous.

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 when-to-use (user explicitly asks about the signed-in account itself), explicit when-NOT (do not use to confirm a Meta/YouTube onboarding attempt, do not enumerate artists), and names the correct alternatives for each exclusion (dynamoi_get_platform_status, dynamoi_list_artists). It even rules out a misuse pattern ('check context' before generic questions), which is unusually thorough routing guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely new behavioral context: format=summary produces a relayable written verdict, and the 'if this tool already returned the comparison, stop' rule prevents redundant calls. It does not mention rate limits, auth requirements, or dateRange defaults, but that is a modest gap against covered annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the user questions it answers, then parameter guidance, then the stop rule and the alternative. Every sentence has a job, though the quoted user phrasings and the restated summary-format benefits make it slightly longer than strictly necessary.

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 no explanation. For a four-parameter read-only analytics tool, the description covers when to invoke it, which parameters to set for which intent, when to stop, and which sibling to use instead. Nothing an agent needs to call 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 0%, so the description carries the load, and it does explain the two non-obvious enum parameters: what granularity=DAILY means and what format=summary yields (written rollup, strongest-campaign verdict). artistId and dateRange get no explicit semantics, though their names, UUID format, and start/end patterns make them largely self-evident.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (artist-level performance analytics across all campaigns) and scopes it with 'including 30-day rollups or daily breakdowns'. It explicitly routes the one-campaign case to dynamoi_get_campaign, so an agent can distinguish it from its closest sibling without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete user-intent triggers ('how is my release doing?', 'are my ads working?'), states which parameter to pass for which sub-intent (granularity=DAILY for daily breakdowns, format=summary for a written rollup or verdict), and names the alternative (dynamoi_get_campaign with includeAnalytics=true) for one campaign. It even specifies a stop condition after a strongest-campaign comparison.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the response source ('audience analytics'), that it preserves the requested date range, and an explicit failure-mode instruction to report unavailability rather than reporting zero audience.

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 tight sentences, front-loaded with the trigger condition, then the parameter guidance, then the failure-mode caveat. Little waste; only the restated default slightly duplicates the schema.

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 explanation is unnecessary, and the description covers the trigger, the parameter choice, and the degraded-source case. The only gap is the absence of sibling routing guidance against dynamoi_get_artist_analytics and dynamoi_get_playlist_analytics.

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 parameter meaning. It restates the range enum values and the 30d default, which the schema already declares, and says the date range is preserved in the response — but adds no detail on artistId semantics or how the range affects aggregation/granularity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('audience analytics') and enumerates the exact dimensions delivered: country, service, paid/free tier, daily trend. It does not explicitly differentiate itself from the sibling dynamoi_get_artist_analytics, so an agent must infer the boundary between 'audience' and 'artist' analytics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear triggering condition ('use this when the user asks about an artist's streaming audience by country, service, paid/free tier, or daily trend') and specifies the range parameter choice and its default. It stops short of naming when not to use it or which sibling to prefer for adjacent questions.

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

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

Annotations already establish the safe read-only profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds real behavioral context beyond them: YouTube campaigns return youtubeStrategy/strategyGuide that must be interpreted via the guide's goal and judgeBy, and channel results include organic views never attributed to the campaign.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the key routing rule are front-loaded, and the guidance on flags and the summary format follows in a logical order. It is dense but each sentence carries actionable information; only the YouTube interpretation clause is a touch verbose.

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 need not explain return values, and it covers when-to-use, sibling routing, flag semantics, and interpretation caveats well. The main residual gap is the analytics date-range/granularity parameters, which are neither in the schema nor the description.

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 compensate. It meaningfully documents the includeAnalytics, includeChannelResults, includeDeploymentStatus, and includeCountries flags with the conditions that select them, but leaves analyticsDateRange, analyticsGranularity, and the campaignId format unaddressed.

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 ('get full details for one campaign') and enumerates the payload (budget, targeting, platform status, next actions). It explicitly distinguishes itself from the sibling dynamoi_list_campaigns, so an agent can route correctly without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use conditions for each optional flag (includeAnalytics for paid delivery, includeChannelResults for observed YouTube results, includeDeploymentStatus for blockers, includeCountries only when the full list is needed) and a clear when-not-to-use rule pointing to dynamoi_list_campaigns. It also prescribes format=summary for post-launch follow-up reads.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered, and the description goes well beyond them by enumerating the five checks performed and clarifying that meeting all five only permits an application, not approval. It does not discuss rate limits or response shape, but the output schema covers returns, so this is strong without being exhaustive.

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 trigger phrases and core capability are front-loaded, and the requirement list is compact. The paragraph is dense and runs long, but each sentence carries routing or eligibility information rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only eligibility check with an output schema handling the return values, the description covers what the tool does, when to invoke it, what it verifies, the limits of its verdict, and what to do when dependent tools are missing. Nothing needed to call it correctly is absent.

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% and the description never mentions the single artistId parameter, so it adds no semantic detail beyond the schema. The parameter is nonetheless self-describing (a UUID artist identifier) and there is only one, which keeps the practical gap small.

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: it checks whether an artist qualifies for Dynamoi distribution, enumerates the five requirements, and reports the status of an existing application. It is clearly separable from siblings like dynamoi_apply_for_distribution, which the 'permits an application but never guarantees approval' line implicitly positions as the follow-on action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names the exact user phrasings that should trigger it ('get my music on Spotify', 'distribute my song') and the question types it answers (qualification, requirement list, application status). It also routes the agent to a sibling path (purpose=distribution_identity for missing Meta/YouTube identity) and supplies an explicit fallback message and dashboard URL when those tools are unavailable.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds real behavioral value on the response side — it warns that results carry status, coverage dates and limitations, that unavailable/stale status must be preserved, and that a missing metric must not be read as zero. It does not mention auth or rate-limit behavior, so it is strong but not exhaustive.

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, no filler, with the trigger condition front-loaded. The second sentence packs status/coverage/limitations and the missing-metric caveat into one dense clause chain, which is slightly heavy but each element 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?

An output schema exists, so return values need not be enumerated, and the description still adds interpretation guidance about status and missing metrics. Combined with clear triggers and domain scoping, an agent has enough to invoke it correctly; only the artistId source/format and sibling disambiguation are left implicit.

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 one parameter (artistId, UUID) at 0% schema description coverage, and the description never mentions it or explains that it must be the artist's UUID from dynamoi_list_artists. With a single obvious identifier this is a minor gap, but the description contributes nothing beyond the schema here.

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 concrete outputs — monthly listeners, listener growth over time, growth audit/score, playlist reach, and growth recommendations — so an agent can tell what the tool returns. It also carves out a domain boundary ("Spotify and market insight data, not paid campaign performance"), which separates it from campaign siblings, though it does not distinguish itself from dynamoi_get_artist_analytics or dynamoi_get_audience_analytics.

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 an explicit trigger clause ("Use this when the user asks for...") with several concrete user phrasings, plus an exclusion for paid campaign performance data. It stops short of naming the alternative tool an agent should call instead for adjacent questions.

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

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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real behavioral context beyond that: the polling-after-connection-start use case and the ops-correlation role of onboardingAttemptId/onboardingFlow. It does not mention rate limits, freshness, or caching, which would round it out.

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 primary trigger, then the polling detail, then exclusions. Each sentence contributes, though the 'Never use this to personalize generic Instagram or marketing-advice questions' line is oddly scoped for a platform-connection tool and reads as boilerplate.

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 need not explain return values, and it covers the main when/when-not plus the onboarding correlation params. The gaps are artistId semantics and the meaning of the format enum, minor against the structured coverage that already exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description carries the parameter burden, but it only addresses two of four params (onboardingAttemptId, onboardingFlow) and even there the phrase 'the returned onboardingAttemptId' is ambiguous about where it comes from. The required artistId and the format enum get no explanation in either place.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a concrete resource and scope: connection status for Spotify, Meta, and YouTube plus the setup steps blocking launches. An agent can tell this apart from billing and generic marketing questions. It stops short of differentiating from adjacent siblings like dynamoi_get_account_overview or dynamoi_get_youtube_channel_data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit trigger ('when the user wants to know whether ... are connected'), a specific polling context after a connection-start flow, and two explicit exclusions (billing, Instagram/marketing-advice personalization). No sibling alternative for platform status is named, so it is clear but not fully routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is settled. The description adds valuable domain context: the response includes freshness and snapshot dates, and these are observed placements not attributed to a paid campaign. This is meaningful behavioral disclosure beyond annotations, though it omits error handling or rate-limit context.

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 three tight sentences, front-loaded with the usage trigger, followed by response content and an important caveat. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return value documentation is not needed. The description still adds useful context about freshness/snapshot dates and non-attribution to campaigns. The only gap is that it doesn't elaborate on the artistId parameter, but given the single simple parameter, this is minor.

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 only one parameter (artistId), and schema coverage is 0%, but the parameter name and UUID format in the schema make its meaning self-evident. The description doesn't discuss the parameter at all, but with a single obvious identifier, the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb+resource combination: it explains the tool returns an artist's tracked playlist placements, reach, and playlist movement. It's specific about what the tool does, though it doesn't explicitly distinguish itself from siblings like dynamoi_get_artist_analytics or dynamoi_get_audience_analytics.

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 provides a clear when-to-use trigger: 'Use this when the user asks about an artist's tracked playlist placements, reach, or playlist movement.' This gives an agent a concrete condition for selecting this tool. It doesn't mention alternatives or exclusions, but the trigger is specific enough to route correctly in most cases.

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

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

Annotations already establish this as a safe, read-only, non-open-world call, so the description's job is to add context — and it does, via the conditional-expansion flags and an output-handling rule ('lead with the public URL and do not expose internal IDs unless asked'). It says nothing about authorization scope, rate limits, or behavior when the identifier doesn't resolve, which are the remaining gaps.

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 tight sentences: trigger first, flag guidance second, output-handling last. No restatement of the title or name, and every clause carries information an agent would otherwise have to guess.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, and the read-only annotations cover the safety profile. But for a 9-parameter lookup with three alternative identifiers and zero schema descriptions, the description leaves the agent unable to determine which key to pass or how the analytics parameters interact.

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% across 9 parameters, so the description carries the full documentation burden, yet it explains only includeAnalytics and includeArtistSettings. It never clarifies the mutually exclusive identifier options (playLinkId vs spotifyUrl vs artistId), what 'format: summary' changes, what dateRange/granularity govern, or what includeBreakdowns returns.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('full details for one free Smart Link') and even enumerates the payload fields (release, Spotify URL, play.dynamoi.com URL, status, theme source, next actions). The word 'one' implicitly separates it from dynamoi_list_smart_links, but no sibling is named explicitly, so it stops 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?

The opening clause is an explicit usage trigger ('Use this when the user wants full details for one free Smart Link'), and it adds conditional guidance for the includeAnalytics and includeArtistSettings flags. There is no when-not guidance and no named alternative for bulk lookups, which keeps it out of the top band.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, but the description adds substantial behavioral context: estimated revenue versus AdSense payout, 2-3 day data latency, revenue lag, unknown versus zero semantics for placeholderDays/missingDays/recovery.state, adsense null conditions, synthetic/sample qualifications, and the fact that no ad spend is returned. This is unusually rich non-contradictory disclosure.

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 massive paragraph with no headers, bullets, or visual separation. Important caveats about latency, null handling, and prerequisites are buried after long dataset enumerations, making it costly for an agent to parse despite much of the content being substantive.

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 complex tool with 8 parameters, no schema descriptions, an output schema, and annotations, the description is highly complete. It covers dataset semantics, freshness caveats, null semantics, prerequisites, and limitations, while the output schema can handle return-value documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must carry parameter meaning. It does well for the dataset enum by listing each dataset's metrics, explains videoIds filtering for video_daily, format=summary behavior, cursor pagination via nextCursor, and implies date-range mapping through windowFromDay/windowThroughDay. It still leaves limit bounds and startDate/endDate mapping largely implicit, so it is strong but not complete.

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 clearly identifies the resource as an artist's connected YouTube channel analytics and enumerates datasets and metrics, but it opens with example questions rather than a crisp verb+resource statement. It also does not explicitly name or distinguish sibling analytics tools such as dynamoi_get_audience_analytics or dynamoi_get_artist_analytics.

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 when to use the tool ('how is my YouTube channel doing?' or 'what is growing my channel?'), gives key prerequisites (channel linked, reconnected channel refused), and names dynamoi_get_campaign for strategy context. However, it lacks systematic comparison against sibling analytics tools, so it falls short of full when/when-not/alternatives guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond that: the fields returned, the shape change when artistId is passed, and the empty-result semantics. It does not mention pagination behavior for cursor 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the primary use case, then the artistId variant, then exclusions, then the empty-result fallback — a logical order with no filler. It is dense, and the negative-instruction sentence is long, but every clause carries routing value.

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 unnecessary, and the description still covers scope, the single-artist variant, sibling alternatives, and the empty-result path. Nothing an agent needs to select or invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning; it explains artistId well (full profile/readiness for one artist vs a roster page) and implies pagination via 'roster page'. However limit, cursor, and format (json/summary enum) are never addressed, leaving half the parameters undocumented in both places.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb+resource ('list artists or YouTube channels they manage') and enumerates the distinguishing payload (billing status, active campaign count, role), which separates it from analytics and campaign tools. The artistId branch is explicitly framed as a single-profile lookup versus a roster page.

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 when-to-use, when-not-to-use (campaign details → dynamoi_list_campaigns / dynamoi_get_campaign; generic social-media advice), and an edge-case routing rule (empty result → dynamoi_get_account_overview.recommendedNextActions). Alternatives are named rather than implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds genuine non-schema context: the prerequisite that an artist must exist and the redirect path when it does not. It stops short of describing pagination behavior (limit/cursor) or the json vs summary format trade-off.

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, all front-loaded, with the positive use case first, the sibling exclusion second, and the precondition last. No filler or restated name/title text; every sentence carries routing or constraint 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?

For a list tool with an output schema, return-value explanation is unnecessary, and the annotations cover safety. The description handles routing and disqualification well, but the operator-level details an agent would need (pagination, format selection) are absent from both description and schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across six parameters, so the description must carry the load. It does cover the artist scoping and the two filter params (type, status), but says nothing about limit (max 50), cursor-based pagination, or the format enum (json/summary), leaving three of six parameters undocumented anywhere.

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 (browse campaigns) scoped to one artist, plus the optional filter dimensions (type, status). It explicitly carves out the boundary against dynamoi_get_campaign, so an agent can distinguish the two without inspecting either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use, when-not-to-use ('Do not use this for a single campaign deep dive'), names the alternative tool, and adds a routing precondition ('If the user has no artists yet... route via dynamoi_get_account_overview first'). This is about as complete as usage guidance gets.

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

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

Annotations already declare readOnlyHint/ non-destructive / closed-world, so the safety profile is covered. The description adds genuinely new behavior: presentation rules (show public URLs, hide internal IDs) and the operational fallback when results are empty for a Spotify-connected artist. Pagination/cursor behavior is still undisclosed, which holds it below 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 the use condition, then exclusion, then output guidance and fallback. Four sentences with little waste, though the presentation/fallback tail is longer than strictly needed for tool selection.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape needn't be re-described. For a read/list tool with annotations covering safety, the description covers selection, exclusion, presentation, and empty-state recovery; the only real gap is pagination semantics for limit/cursor.

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% across 8 parameters, so the description carries the burden. It names the filterable states (claim, render, publish) and the artist scope, which maps to several params, but says nothing about limit/cursor pagination, the query string semantics, or the json vs summary format enum.

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 free Smart Links for one artist') and enumerates the fields returned (release title, public URL, publish/claim/render state, theme). It explicitly distinguishes itself from dynamoi_list_campaigns, so an agent can separate it from its closest sibling 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?

Gives an explicit trigger ('when the user wants to list free Smart Links for one artist'), an explicit exclusion with the alternative named ('Do not use this for paid campaign lists; use dynamoi_list_campaigns'), and empty-state routing to two creation siblings. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description still adds value by describing the return states ('authorized artist roster or an honest empty account state') and by enumerating the write actions it deliberately will not perform, which clarifies the scope boundary. It stops short of richer behavioral detail, but the annotation coverage lowers the bar.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with the purpose and empty-state behavior before the exclusions and routing hint. Slightly list-heavy in the negative clause ('create links, change campaigns, start purchases or connect accounts'), but every clause still earns its place by defining scope.

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 zero parameters, an output schema present, and annotations covering the safety profile, the description only needs to convey purpose, scope boundaries and when to use it — all of which it does. An agent has everything required to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is no parameter semantics to document and the baseline is 4. The description correctly adds no redundant parameter talk.

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 ('Open the read-only Dynamoi workspace') and immediately scopes it to browsing artists, campaigns, Smart Links and observed results. It also differentiates itself from the list/get siblings by directing follow-up detail lookups to 'individual read tools.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when ('when the user wants to browse their existing artists, campaigns, Smart Links and observed results in ChatGPT'), explicit when-nots ('Does not create links, change campaigns, start purchases or connect accounts'), and names the alternative path for follow-up details. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by characterizing the output as a visual preview and enumerating the mutations it will not perform (create/publish/update/promote), which reassures an agent about 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the primary use case front-loaded and no filler. The second sentence is somewhat redundant with the readOnly/destructive annotations but still earns its place as an explicit no-side-effects statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter, read-only preview tool with an output schema and full annotation coverage, the description covers purpose, triggers, and safety adequately. The only real gap is the meaning of the two input parameters, which nothing in the definition explains.

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?

Two parameters (artistName, releaseTitle) have 0% schema description coverage and no mention in the description at all. An agent cannot tell from either source whether these are sample values used to render the preview or whether they are required filters, and their optionality is only visible 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 (preview) and resource (Smart Link themes) and immediately scopes it as a visual preview of what Smart Link pages look like. The closing negation (does not create, publish, update, or promote a Smart Link) cleanly separates it from sibling write tools like dynamoi_create_smart_link_from_spotify and dynamoi_update_smart_link.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit trigger conditions: user asks what Smart Link pages can look like, wants to compare themes, or wants to preview before creating/updating. It does not, however, name the sibling tool an agent should pick instead for the actual creation/update path, so the routing is only implied by the negation.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description earns credit beyond that by disclosing the empty-result behavior for brand-new users and instructing the agent not to treat it as terminal, which is genuinely non-obvious. It omits pagination/rate-limit behavior even though a cursor parameter exists, so it is strong but not complete.

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 primary when-to-use condition before the exclusion and the edge-case note. Every sentence is doing work (selection, exclusion, fallback), though the new-user empty-result sentence is long and could be split or tightened. Overall appropriately sized for a search entry point.

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 annotations carry the safety profile. However, with 7 parameters at 0% schema coverage and options like type, format, limit, and cursor, the description leaves an agent without guidance on how to narrow or paginate a search. The definition is usable but incomplete for a multi-filter search 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?

Schema description coverage is 0% across 7 parameters, so the description must carry the burden, and it largely does not. It never mentions type, limit, query, cursor, format, artistId, or includeArchived. At best 'artist, release, campaign, or smart link' loosely gestures at the type enum, but 'release' doesn't even match an enum value, leaving the parameters effectively undocumented.

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 frames the tool around a clear scenario—finding a record when the user names an artist, release, campaign, or smart link but the exact record is unknown—which distinguishes it from the get_* siblings that require a known target. The verb ('search') lives in the name, and the resource scope is implied by the enumerated entity types. It stops short of an explicit one-line statement of what it searches or how results are returned, keeping it just below 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?

It gives an explicit when-to-use condition (unknown record for a named entity) and an explicit when-not (analytics summaries or billing questions once the target is known). It also supplies fallback routing for the empty-result-on-new-user case, pointing to dynamoi_create_smart_links_from_spotify_artist rather than leaving the agent to answer terminally. This covers selection, exclusion, and edge-case routing.

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

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

Annotations already declare destructive, idempotent, openWorld, and non-readOnly, so the bar is lower. The description adds genuinely useful behavioral context: theme-only changes apply instantly while pixel changes may queue background rendering, plus a confirmation safeguard. It doesn't warn that pixel IDs may overwrite existing values, a minor gap against destructiveHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the usage trigger, then scope exclusions and behavioral notes. Sentences are distinct and mostly earn their place, though the confirmation line is somewhat boilerplate.

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 needn't be explained, and annotations carry the safety profile. The description covers scope, timing, and confirmation well; the main shortfall is under-explaining the several non-obvious request parameters.

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% across 7 parameters, so the description must carry the semantics. It loosely maps to theme and pixel settings but explains none of artistId, clientRequestId, userIntentSummary, or the enum values, leaving most parameters undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'change artist-level Smart Link theme or validated pixel settings.' It also bounds the resource precisely, excluding link description changes and publish/unpublish, which cleanly separates it from the sibling dynamoi_update_smart_link_description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear when-to-use trigger ('Use this when the user wants to change...') and explicit exclusions ('cannot change a link description or publish or unpublish links'). It stops short of naming the alternative tools to call instead, but the scope boundary is effectively conveyed.

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

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

Annotations already cover the safety profile (write, idempotent, destructive, open-world), so the description's added value is the async note that 'a description change may queue background rendering' and the confirmation guardrail. It does not, however, explain the destructive/overwrite nature of replacing an existing description or the meaning of destructiveHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, efficiently front-loaded with purpose before the boundaries and caveats. Each sentence contributes, though the separate confirmation sentence could be folded in without loss.

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 no explanation, and annotations plus the rendering note cover the mutation behavior, but with 5 parameters at 0% schema coverage three parameters remain undocumented in both schema and description. Adequate overall, with a clear parameter gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden, yet it names no parameters. It only loosely implies 'customDescription' via 'the requested description', leaving 'expectedUpdatedAt' (concurrency), 'clientRequestId' (idempotency), and 'userIntentSummary' entirely unexplained.

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 (update), a specific resource (one Smart Link's public description), and an explicit scope boundary. It also distinguishes itself from the sibling 'dynamoi_update_smart_link_artist_settings' by declaring it cannot touch artist-level theme or pixel settings.

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?

Front-loads the trigger condition (user wants to update one Smart Link's description), states what it cannot do (artist-level theme/pixel settings, publish/unpublish), and gives a procedural guardrail (confirm the description before calling). When-to-use, when-not, and a pre-call step are all explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds little behavioral context beyond noting the output is 'for citation' – no rate limits, id-expiry, or failure behavior. With annotations carrying the load, a 3 is appropriate.

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 tool's identity and the id-provenance constraint, with no filler. Slightly dense with the 'OpenAI ChatGPT Deep Research / Connectors fetch contract' preamble but overall efficient.

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 needed, and annotations cover safety. For a single-parameter fetch tool the description covers purpose, provenance, and id format adequately; only edge-case behavior is absent.

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 compensate, and it does by spelling out the required id format with three concrete variants ('artist:<uuid>', 'campaign:<uuid>', 'smartlink:<uuid>'). That is genuinely useful meaning beyond the bare `string` type, though it doesn't address length limits.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb/resource: given an id it 'returns the full record for citation.' It also names the companion tool (`search`) that produces the id, so an agent can place it relative to siblings rather than guessing.

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?

Clearly establishes the dependency: it must be called with an id 'returned by `search`,' which is an explicit usage context and ordering constraint. It stops short of stating when NOT to use it (e.g., when you only need list results, use search), so it's not a full 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real context about the contract scope and that results are meant for citation, but says nothing about result limits, pagination, or matching behavior, which matters for a search 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?

Three short sentences, front-loaded with the contract identity, then the return scope, then the routing rule. Every sentence carries distinct information with no repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value details are not needed, and the description covers purpose, scope, and the sibling routing decision. The only real gap is query semantics, which is minor for a one-parameter tool but is the sole input an agent must supply.

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% and the description never mentions the query parameter at all — no guidance on whether it takes keywords, natural-language questions, or entity names, nor what the 120-character cap implies. The schema only supplies length constraints, so the description leaves the single input under-explained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names the concrete resources returned (Dynamoi artists, campaigns, Smart Links) and frames the tool as a specific search contract, so an agent immediately knows what it does. It also explicitly distinguishes itself from the sibling dynamoi_search, which is the key ambiguity in this toolset.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the exact context in which this tool applies (ChatGPT Deep Research / Connectors sessions where results will be cited) and names the alternative with its own condition ("For regular ChatGPT chat use dynamoi_search instead"). This is explicit when-to-use, when-not, and alternative in three sentences.

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