Dynamoi

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

The description goes beyond annotations by explaining the side effect: it 'records an application for manual review' and does not approve distribution, sign agreements, transfer rights, or deliver music. It also adds a nuanced qualifier to the idempotency annotation—'for an active application'—which is valuable behavioral 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 focused sentences with no filler. It front-loads the core action and condition, then efficiently lists exclusions and requirements. Every sentence adds necessary operational context.

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 tool's complexity (7 required parameters, no schema descriptions, a meaningful approval workflow), the description provides sufficient detail for correct invocation: when to call, which parameters must be present, the side effect, and the non-effects. An output schema exists, so not describing return values is acceptable.

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 carries the parameter-documentation burden. It explains that all three two-letter country codes are required, that adultSignerAttestation is a signer attestation, that confirmApplicationSubmission must be true, and that userIntentSummary should be concise. This meaningfully supplements the bare schema, though artistId is not explicitly described beyond 'artist's application.'

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

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

The description uses a specific verb and resource ('Submit an artist's application for Dynamoi music distribution') and clearly scopes what the tool does and does not do. It distinguishes itself from related operations like approving, releasing, or configuring splits, making its role unambiguous alongside siblings such as dynamoi_get_distribution_application and dynamoi_launch_campaign.

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 states the condition for use ('after the user explicitly asks to apply and all five eligibility requirements are met') and gives a clear when-not-to-use list via what it does not do. It does not name alternative sibling tools explicitly, but the behavior boundaries are sufficient for an agent to route correctly.

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

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

The description adds rich behavioral context beyond annotations: idempotency ('return the existing link instead of creating a duplicate'), verification hold ('may stay unpublished in verification hold'), the fact that it is free and does not create a paid ad campaign, and the update behavior for customDescription. No contradiction with the provided annotations.

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

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

One focused paragraph front-loads the primary usage rule, then efficiently covers caveats, exceptions, and output handling. Every sentence adds value—no filler or repetition.

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?

Despite the presence of an output schema and annotations, the description covers edge cases (playlists, duplicates, verification hold), non-goals (ad campaign creation), and final answer formatting. It is thorough enough for an agent to select and invoke the tool correctly in varied situations.

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 for explaining parameters. It only clarifies spotifyUrl (album/track/artist URL/URI) and customDescription (updates public description). Required artistId is left unexplained, and format, clientRequestId, and userIntentSummary have no semantic clarification despite non-obvious names.

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

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

The description uses a specific verb+resource ('create one free Dynamoi Smart Link from a Spotify album or track URL/URI') and clearly distinguishes itself from the sibling tool for full-catalog artist imports by naming the alternative. This makes the tool's purpose immediately clear and unique among 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?

Explicitly states when to use this tool ('Use this when the user wants to create one free...'), when not to use it ('Spotify playlist URLs are not supported today'), and names the preferred alternative for other cases ('For full-catalog artist imports or artist hub requests, prefer dynamoi_create_smart_links_from_spotify_artist').

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

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

The annotations already indicate mutation and destruction, but the description adds crucial context: background catalog import starts without dashboard need, verification hold for high-popularity/unverifiable links, and the instruction to lead with artist hub URL and avoid exposing internal IDs. These details go beyond the annotation hints and help the agent manage user expectations safely.

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 dense but every sentence earns its place: trigger condition, artistId nuance, background behavior, free status, verification hold, ad campaign exclusion, and output guidance. It is not overly verbose, though it could be restructured slightly to separate main actions from caveats.

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 tool's complexity (5 params, background import, verification holds, output responsibilities), the description covers the key operational scenarios, edge cases (unverifiable artists), and interaction requirements (leading with hub URL). The presence of an output schema means return format details are not required, and the description provides sufficient guidance for an agent to invoke and present results 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?

With schema description coverage at 0%, the description needed to explain the parameters. It only meaningfully covers artistId ('omit artistId so Dynamoi can create the first artist'), leaving format, clientRequestId, and userIntentSummary unexplained. While enum values and types are in the schema, the description does not add semantics for these parameters, which is a significant gap.

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

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

The description clearly states the tool's function: 'create, import, or refresh free Smart Links for the artist catalog and return the artist hub.' It specifies the resource (Spotify artist catalog) and verb (create/import/refresh), and distinguishes from sibling tools like dynamoi_create_smart_link_from_spotify by referencing the plural 'smart links' and catalog-wide operation.

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 opens with 'Use this when...' and gives a specific trigger (user provides Spotify artist URL wanting Dynamoi to create/import/refresh links). It includes conditional guidance (omit artistId if no Dynamoi artist yet), explains background import implications, and explicitly excludes paid ad campaigns, which sets it apart from dynamoi_launch_campaign.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only behavior is covered. The description adds useful contextual behavior: account-level state can span multiple artists, making this tool inappropriate for single-artist platform confirmation. It could go further by describing what the returned overview contains, but the output schema likely covers that.

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

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

The description is front-loaded with the core use case, then provides precise exclusions and alternatives. Every sentence earns its place; there is no filler or vague 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?

Given the output schema exists, the description does not need to explain return values. It fully covers invocation conditions, required intent behavior, exclusions, and sibling routing, which is complete for a read-only account-overview 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 compensate. It does so for the required intent parameter by explaining that it should match the explicit account question, and the prose lists the relevant concerns (organizations, artists, platform connections) that map to the intent enum. The optional format parameter is not discussed, but json/summary are self-explanatory.

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: it is for explicit questions about the signed-in Dynamoi account itself (who is logged in, organizations/artists accessible, account-level platform connections). It also explicitly distinguishes itself from sibling tools like dynamoi_list_artists and dynamoi_get_platform_status, so there is no ambiguity about what this tool is for.

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 gives crystal-clear when-to-use guidance and equally clear when-not-to-use guidance. It names the exact alternatives (dynamoi_get_platform_status for artist-specific onboarding, dynamoi_list_artists for enumeration) and explicitly forbids using this tool as a generic context-check before answering unrelated 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 mark the tool as read-only and non-destructive, so the description doesn't need to restate safety. It adds useful behavioral context: the summary format returns a strongest-campaign verdict and a written rollup, and the tool can produce daily breakdowns. It also tells the agent to stop calling more analytics tools once the comparison is returned. No contradictions with 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?

Every sentence earns its place: purpose, parameter triggers, stop condition, and sibling routing are all included without fluff. The most important scope information is front-loaded. No redundant restatement of the tool name or title.

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

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

Combined with an output schema and read-only annotations, the description covers the key selection logic, parameter triggers, alternative routing, and the stop condition. The main gap is the lack of explicit guidance on dateRange/default behavior, but the schema provides structure and the description mentions 30-day rollups contextually.

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 for parameter meaning. It explains when to set granularity=DAILY and format=summary, which addresses two enum parameters. However, it does not explain dateRange semantics, default values, or what format=json implies beyond what the schema already provides.

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: retrieving artist-level performance across all campaigns. It distinguishes itself from the sibling dynamoi_get_campaign, which is for one campaign's metrics. The scope ('across all campaigns') and resource ('artist analytics') are clearly identified.

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

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

Explicitly says when to use this tool ('artist-level performance across all campaigns') and when to use the alternative ('For one campaign's metrics, use dynamoi_get_campaign'). It also gives concrete parameter instructions for granularity=DAILY and format=summary, plus a stop-and-answer rule after the strongest-campaign comparison is returned.

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

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

Annotations already mark this read-only and non-destructive, and the description adds useful behavioral context beyond that: which optional flags control what data is included, and how format=summary behaves for follow-up reads. It does not explain defaults or detail response behavior, but the output schema and annotations cover the core safety profile.

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, no filler, with the primary purpose front-loaded and conditional guidance following logically. 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?

The description is strong for a read-only single-campaign lookup: it explains scope, filtering flags, alternatives, and a follow-up read mode. Minor gaps remain around analyticsDateRange/analyticsGranularity usage and defaults, but output schema and annotations fill in much of the remaining picture.

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 burden, and it does explain includeAnalytics, includeDeploymentStatus, includeCountries, and format. However, analyticsDateRange and analyticsGranularity are left unexplained and their relationship to includeAnalytics is not clarified.

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 states the tool fetches full details for one campaign, including budget, targeting, platform status, and next actions. It also explicitly distinguishes itself from the list alternative, making its purpose unambiguous.

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

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

It provides explicit when-to-use guidance ('when the user wants full details for one campaign') and an explicit when-not-to-use rule with a named alternative ('use dynamoi_list_campaigns instead'). It also gives practical advice about when to prefer format=summary after mutations.

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

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

Beyond the readOnlyhint and destructiveHinct, the description is narrates the five concrete eligibility checks, states that meeting all five does not guarantee approval, and clarifies that identity connections do not require advertising billing. It accurately confirms the read-only nature behavior and adds important context. No annotation contradiction.

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 most important use signal is front-loaded and each sentence contributes operational guidance. The list of five requirements is somewhat dense, but given the tool's complexity it is not wildly since long. It could be tightened slightly but still earns its length.

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 tool that checks eligibility and status, the description fully covers when to use it, the five eligibility conditions, the approval caveat, and the fallback routing for missing face/meta or YouTube connections. With an output schema present, no essential behavior is unexplained.

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

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

The schema description coverage is 0%, so the description was expected to compensate for the lone artistId parameter, but it never mentions that parameter. The property name and UUID format make the vague likely, but the description itself adds no direct semantic guidance about what identifier to pass or where it comes from.

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 begins with 'Use this when the user asks...' and enumerates three specific intents: eligibility, the five requirements, and existing application status. The resource (distribution application) and the action (get/check) are clear, so it cannot be confused with apply_for_distribution.

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 triggers for using the tool and tells the agent what to do instead for missing identity: use another tool with purpose=distribution_identity or route the user to the Dynamo distribution application. This clearly separates it from the sibling connection and application tools.

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 read-only safety profile. The description adds useful behavioral context: after a connection-start flow, the agent should pass the returned onboardingAttemptId and onboardingFlow so Dynamoi ops can correlate the browser step. No contradiction with 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?

Three sentences with the main use case front-loaded and no filler. The polling instruction and exclusions each earn their 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 and read-only annotations, the description covers the main selection and invocation concerns, including the non-obvious polling flow. The missing explanation of artistId and format keeps it slightly incomplete.

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 bears the burden for explaining parameters. It adds real meaning for onboardingAttemptId and onboardingFlow, but never explains the required artistId or the format enum, leaving two of four parameters under-specified.

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 states the tool reports whether Spotify, Meta, or YouTube are connected and which setup steps block launches. This sharply differentiates it from analytics, smart-link, campaign, and account-overview 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?

It gives explicit 'Use this when...' context, polling guidance with onboarding IDs, and clear exclusions for billing and generic marketing questions. It stops short of naming an alternative tool for those exclusions, so it is 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 and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail about response presentation (lead with public URL, avoid internal IDs) and optional analytics/theme flags, but does not disclose behavior for ambiguous invocations such as no identifier or conflicting identifiers.

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 focused sentences with no filler; the primary purpose is front-loaded, optional flags are grouped, and the response formatting rule is a single clear instruction. 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?

For a 9-parameter tool with no schema descriptions and no required parameters, the description leaves a critical gap: how the agent should identify the target Smart Link (via playLinkId, spotifyUrl, aristsId, or some other route) and what dateRange/granularity/format control. The presence of an output schema helps, but not enough to make the tool safely invocable.

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 for the heavily undocumented parameters. It only explains includeAnalytics and includeArtistSettings, leaving format, artistId, dateRange, playLinkId, spotifyUrl, granularity, and includeBreakdowns 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?

The description names a specific verb and resource ('full details for one free Smart Link') and enumerates the returned content: release, Spotify URL, public URL, status, theme source, and next actions. This clearly distinguishes the tool from sibling list/create/update tools.

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

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

The opening 'Use this when the user wants full details for one free Smart Link' gives clear selection context, and 'one' differentiates it from list-oriented siblings. However, it does not explicitly mention alternatives or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety profile is established. The description adds value beyond that by explaining the roster-vs-profile behavioral split and, notably, the semantic meaning of an empty response (brand-new user, route to recommendedNextActions rather than reporting 'no records found'). No contradiction with 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?

Four sentences, all earning their place: primary use case, artistId variant, exclusion routing, and empty-result behavior. Information is front-loaded with the main purpose first. Slightly dense as one paragraph, but there is 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 tool with 4 optional params, an output schema, and 15 siblings, the description covers when to use it, what it returns, what it excludes, the artistId variant, and the empty-result edge case. Remaining gaps are minor: no mention of pagination behavior (limit/cursor) or the format enum, though those are optional and conventional.

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 for parameter meaning, but it only addresses artistId ('pass artistId when you need the full profile/readiness details for one artist'). It adds nothing for limit, cursor, or format — pagination semantics and the json/summary distinction are left completely 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?

The description states a specific verb+resource: listing artists/YouTube channels the user manages, and names the exact fields returned (billing status, active campaign count, role). It distinguishes itself from siblings by naming dynamoi_list_campaigns and dynamoi_get_campaign as the campaign-detail tools, and by contrasting roster-page output with full-profile output.

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 the user wants to see which artists or YouTube channels they manage'), when-to-pass-artistId, and clear exclusions with named alternatives ('Do not use this for campaign details; use dynamoi_list_campaigns or dynamoi_get_campaign'). It even handles the edge case of an empty result with routing instructions to dynamoi_get_account_overview.recommendedNextActions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral detail such as pagination behavior, response format differences, or rate limits; it focuses on selection guidance rather than operational behavior.

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

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

Three sentences, each with a distinct purpose: when to use, what not to use it for, and a prerequisite routing rule. No wasted words, and the primary use case is front-loaded.

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

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

For a read-only list tool with an output schema present, the description covers selection criteria, exclusions, and an important prerequisite. The only meaningful gaps are undocumented pagination parameters and the meaning of the 'summary' format, which keep it from being fully 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?

Schema description coverage is 0%, so the description must compensate. It clarifies the role of artistId, status, and campaignType, but leaves limit, cursor, and format unexplained. The format enum (json vs summary) is especially ambiguous without further context.

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 ('browse'), a concrete resource ('campaigns for one artist'), and optional filters ('by type or status'). Explicitly distinguishes itself from dynamoi_get_campaign, making the tool's scope immediately identifiable.

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 guidance, clear exclusions ('Do not use this for a single campaign deep dive'), names the alternative tool, and even gives a routing prerequisite when the user has no artists yet. This leaves little 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=true and destructiveHint=false, establishing a safe read operation. The description adds behavioral context beyond this: instructs to show public URLs and avoid internal IDs in the final answer, and describes the desired fallback behavior for empty results. No contradiction with 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?

Four sentences, each earning its place: purpose, exclusion, output formatting rule, and empty-case fallback. Front-loaded with the primary action and no filler or repetition.

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?

The description covers purpose, when-not-to-use, output presentation, and fallback behavior, and an output schema exists. However, with 8 parameters and no parameter descriptions, the lack of explanation for filtering/pagination options leaves some gaps, though the core invocation is clear.

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, but it does not explain any of the 8 parameters beyond implying artistId via 'one artist'. The filter parameters (limit, query, cursor, format, claimStatus, renderState, publishState) are left completely unexplained, offering no added meaning over the raw 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 opens with a specific verb ('list'), resource ('free Smart Links for one artist'), and enumerates returned fields ('release title, public URL, publish state, claim state, render state, and theme'). It explicitly distinguishes from the sibling tool `dynamoi_list_campaigns`, making purpose 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?

Provides direct when-to-use guidance ('Use this when the user wants to list free Smart Links for one artist'), an explicit exclusion ('Do not use this for paid campaign lists; use dynamoi_list_campaigns'), and alternative actions when results are empty (suggesting create tools). This is exemplary.

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 provide readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'read-only visual preview' and explicit non-actions like 'does not create, publish, update, or promote.' This adds useful context about the tool's non-mutating nature beyond the raw annotation flags, though it does not go into depth about return behavior or edge cases.

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 entire description is a single well-structured sentence that front-loads the use cases and then states exclusions. Every part earns its place, with no filler or redundant phrasing.

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?

The description covers purpose, usage context, and safety profile, and an output schema exists to explain return values. However, it omits any guidance on the two optional parameters, which are undocumented in the schema as well. This leaves an agent uncertain about whether or how to populate artistName and releaseTitle when invoking the 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%, and the description does not mention artistName or releaseTitle at all. The parameter names are somewhat self-explanatory, but the description fails to explain how these optional parameters affect the preview, what they are used for, or why an agent should supply them. The description needed to compensate for the missing schema descriptions but did not.

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 action ('preview Smart Link themes') and resource, and clarifies it is a visual preview rather than a create/update/publish operation. It clearly distinguishes itself from sibling create/update tools by explicitly listing what it does not do.

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 gives explicit triggers: when the user asks what themes look like, wants to compare themes, or wants to preview before creating/updating a Smart Link. It also tells the agent when not to use it by stating it does not create, publish, update, or promote a Smart Link, which routes the agent away from this tool for mutation tasks.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to repeat safety traits. It adds non-obvious behavior: an empty result for a brand-new user should not be treated as a terminal 'no records found' answer, but instead should prompt a suggestion to create the first artist hub. This is useful context beyond the schema.

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

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

Three sentences, each with a distinct purpose: primary use case, exclusion, and empty-result fallback. No fluff and no repetition of schema or annotation information. The most important usage guidance is front-loaded.

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

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

The description covers the central search flow, the key exclusion, and a helpful empty-result edge case, and the output schema supplies return structure. However, it leaves gaps around optional parameters such as format, cursor, and includeArchived, and the 'release' mention does not map cleanly to any type enum value, so an agent may need extra inference for certain searches.

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 burden of explaining the seven parameters, but it only loosely maps the search scenario to 'artist, release, campaign, or smart link'—and 'release' is not one of the type enum values. It does not explain query matching, cursor pagination, the difference between json and summary formats, artistId filtering, or includeArchived, leaving the agent to guess from names and enums.

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 exploratory use: searching when the user mentions an artist, release, campaign, or smart link but the exact record is unknown. It clearly distinguishes from analytics/billing flows by saying not to use it once the target record is known. However, it does not explicitly contrast search with the list_* sibling tools, so some ambiguity remains.

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

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

The description explicitly gives the trigger condition, states when not to use the tool (analytics summaries or billing questions once the target is known), and provides a concrete alternative for the empty-result case on a brand-new user account by naming dynamoi_create_smart_links_from_spotify_artist. This is strong routing guidance with little 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?

Adds real behavioral context beyond annotations: two action modes, artist-wide scoping, no publish/unpublish, and sync vs background rendering. It does not detail destructive consequences despite destructiveHint=true, but annotations already flag that risk.

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?

Tight three sentences: trigger, action values, publishing boundary, and timing behavior. Every sentence earns its place with no repetition of schema content.

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 an 11-parameter, two-mode mutation tool with 0% schema coverage, this description is too thin. An agent cannot reliably know which IDs are required per action or what evidence fields like clientRequestId, expectedUpdatedAt, and userIntentSummary mean, even though an output schema 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 description coverage is 0%, so the description carries the burden. It explains action's enum and the theme/pixel/description concepts, but leaves artistId, playLinkId, pixel IDs, clientRequestId, expectedUpdatedAt, userIntentSummary, and googleAdsConversionId unexplained and does not map parameters per action.

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 explicit use cases: changing a Smart Link's public description or updating artist-level theme/pixel settings. The update role is unambiguous against sibling create/get/list tools, and it explicitly rules out publish/unpublish behavior.

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

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

Opens with 'Use this when...' and gives concrete triggers. It excluds publish/unpublish operations and clarifies artist-wide availability, though it does not name exact alternative tools for those 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 declare readOnlyHint=true and destructiveHint=false, covering the safety profile, so the bar for additional disclosure is lower. The description adds modest behavioral context — this is a 'contract' returning 'the full record' as opposed to search snippets — but it does not disclose error behavior, not-found handling, or any response characteristics beyond completeness.

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 no real waste, and the actionable detail — ID format and return value — is front-loaded in the second sentence. The opening clause ('OpenAI ChatGPT Deep Research / Connectors fetch contract') partially duplicates the title 'Fetch (OpenAI Connectors)', a minor redundancy, but overall the definition is appropriately sized.

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

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

For a single-parameter, read-only tool with an output schema present, the description is nearly sufficient: it covers the input format, the source of the id, and the purpose of the return value. The gaps are minor — no statement about what happens when an id is invalid or not found, and no explicit differentiation from the get_* siblings — but nothing critical is missing for basic invocation.

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 bare schema offers only a string with min/max length; the description carries the full burden and largely succeeds. It specifies the exact accepted formats ('artist:<uuid>', 'campaign:<uuid>', 'smartlink:<uuid>') and the parameter's provenance (returned by search), which is precisely what an agent needs to construct a valid call. It stops short of saying whether other prefixes are possible, leaving a small edge-case gap.

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

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

The description clearly states the verb (returns), resource (full record), and the precise input contract (id formatted as 'artist:<uuid>', 'campaign:<uuid>', or 'smartlink:<uuid>'). This materially distinguishes fetch as a cross-entity retrieval tool versus the more specific dynamoi_get_campaign, dynamoi_get_smart_link, and other get_* siblings, though it never explicitly names those alternatives.

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

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

The description establishes an implicit usage precondition: the id must come from `search`, tying the two tools into a workflow. The phrase 'for citation' hints at the intended downstream use case. However, it gives no explicit when-to-use/when-not-to-use guidance versus the many dynamoi_get_* sibling tools, so an agent must infer the routing decision.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful scoping about which entities are searched and why, but it does not clarify search behavior such as fuzzy vs. exact matching or result limits. With annotations covering side effects, 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?

The description is two sentences, front-loads the tool's purpose and scope, and wastes no words. The alternative-tool mention is placed at the end without diluting the primary message.

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

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

For a single-parameter, read-only search tool with an output schema and clear annotations, the description is largely complete. It covers what is searched, why, and which sibling to use instead. It loses a point because it does not address edge cases like empty results or whether queries are partial or exact matches.

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

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

The schema only defines query as a string with length constraints, and schema description coverage is 0%. The description adds meaning by indicating the query is matched against artists, campaigns, and Smart Links, but it does not explain query format, examples, or matching semantics beyond that.

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 and resource: it returns matching Dynamoi artists, campaigns, and Smart Links for use in deep-research sessions. It also explicitly distinguishes this tool from dynamoi_search, so an agent can tell them apart without inspecting 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?

The description gives explicit context: use this tool for OpenAI ChatGPT Deep Research / Connectors sessions, and use dynamoi_search for regular ChatGPT chat. This is a direct when-to-use vs. alternative-tool instruction.

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