Dynamoi

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=true), the description explains key behaviors: existing links are reused rather than duplicated, customDescription updates the existing link, high-popularity/unverifiable links may remain unpublished under verification hold, and the final answer must lead with the public URL. These details align with the annotations and add significant 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 a single focused paragraph that front-loads the primary use case, then delivers constraints and behavior in each sentence. No redundant or filler content; it's appropriately sized for the tool's complexity.

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 6 parameters, annotations, and output schema, the description covers input scenarios, unsupported types, idempotency, update behavior, verification hold, and response presentation. Minor gaps remain (e.g., no explicit mention of error handling or the exact role of artistId), but overall it is sufficiently complete for an agent to select and invoke the tool 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 description adds behavior for customDescription (updates public description) and implicitly covers spotifyUrl/format, but does not explain artistId, clientRequestId, userIntentSummary, or format semantics. With 0% schema coverage, this leaves several parameters underspecified, though parameter names provide some inherent meaning.

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 explicitly states the tool creates one free Dynamoi Smart Link from a Spotify album/track URL/URI or a single starter release, and it distinguishes from sibling dynamoi_create_smart_links_from_spotify_artist by directing full-catalog imports to that tool. This provides a specific verb, resource, and scope.

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 clearly states when to use (single link from album/track/URI or starter release) and when not to (full-catalog imports, prefer sibling, Spotify playlist unsupported). It also clarifies that no paid ad campaign is created, which prevents misuse.

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 indicate destructiveHint=true, so the description doesn't need to restate that. It adds meaningful behavioral context: starts a background catalog import, may put links in verification hold, and is free. It doesn't explicitly warn about destructive side effects, but 'refresh' implies possible overwriting, and the annotation covers the safety hint.

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

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

The description is front-loaded with the primary use case, then covers parameter nuance, side effects, and final answer format. Every sentence adds value, though it is slightly long. It avoids 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?

Given an output schema and annotations, the description covers key aspects: trigger, artistId omission, background import, verification hold, non-paid nature, and final response format. The only gap is a clear statement of destructive effects, but the annotation covers that, so completeness is strong.

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 spotifyArtistUrl (user-given URL) and artistId (omit to create new artist), but leaves format, clientRequestId, and userIntentSummary unexplained. This partially compensates but not fully for a 5-parameter schema.

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

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

The description clearly states the tool's action: 'create, import, or refresh free Smart Links for the artist catalog and return the artist hub.' It specifies the trigger (user provides a Spotify artist URL) and the scope (artist catalog), distinguishing it from the sibling tool dynamoi_create_smart_link_from_spotify, which handles a single 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?

It provides explicit when-to-use context ('Use this when the user gives a Spotify artist URL...'), a conditional parameter directive ('If the signed-in user has no Dynamoi artist yet, omit artistId...'), and exclusions ('This does not create a paid ad campaign'). It also explains the background import benefit, giving clear guidance on when this tool is appropriate.

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 core safety profile is known. The description adds valuable behavioral context: account-level state spans multiple artists, so it is not a substitute for per-artist platform status. It also imposes a behavioral requirement to always pass a matching intent. This goes beyond annotations without contradicting them.

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?

Although the description is longer than average, every sentence earns its place. It is front-loaded with the primary use case, then provides clear exclusions and alternatives. No wasteful phrasing 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?

For a read-only account overview tool with an output schema and strong annotations, the description is complete. It covers the scope, boundaries, and relationship to sibling tools. Since an output schema exists, omitting return values is acceptable. The description provides all needed context for an agent to invoke 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?

Schema description coverage is 0%, but the description partially compensates by explaining the meaning of the intent parameter ('who is logged in, how many organizations or artists it can access...'). However, the format parameter (json/summary) is not mentioned at all, and the exact enum values for intent are not enumerated or mapped to the described scenarios. So the description adds some semantic value but does not fully compensate for the missing schema descriptions.

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 defines the tool as retrieving account-level overview ('who is logged in, how many organizations or artists it can access, or whether account-level platform connections exist'). It explicitly distinguishes from sibling tools like dynamoi_get_platform_status and dynamoi_list_artists, making the 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 excellent when-to-use guidance ('Use this when the user explicitly asks about the signed-in Dynamoi account itself') and explicit when-not-to-use conditions, including naming alternative tools (dynamoi_get_platform_status, dynamoi_list_artists) and warning against generic context checking. This is the gold standard.

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 meaningful behavioral context beyond annotations: the tool can produce a written summary with a strongest-campaign verdict, and it instructs the agent to stop and answer rather than chain additional analytics calls.

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: the first defines scope, the second and third give parameter behavior, and the fourth names the sibling alternative. Information is front-loaded and there is zero redundancy or 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?

Given the tool has an output schema (covering return values), readOnlyHint/destructiveHint annotations, and a moderate 4-parameter schema, the description supplies the missing usage context: when to use, when not to use, parameter guidance, and a stopping rule. This is complete enough for an agent to select and invoke correctly without additional assumptions.

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%, but the description compensates by explaining the semantics of granularity (DAILY for daily breakdowns) and format (summary for written rollup/verdict). It does not explicitly describe dateRange or artistId, but artistId is obvious from the required schema and title, and dateRange is implied by the '30-day rollups or daily breakdowns' context. This partial compensation is sufficient for the two enum parameters.

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 a specific verb+resource: retrieving artist-level performance analytics across all campaigns. It explicitly distinguishes itself from per-campaign analytics by directing users to dynamoi_get_campaign for single-campaign metrics.

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 (artist-level performance across campaigns, daily breakdowns, summary answers), parameter-specific instructions (granularity=DAILY, format=summary), and a clear exclusion/alternative (use dynamoi_get_campaign with includeAnalytics=true for one campaign). It also instructs stopping after a strongest-campaign result 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 declare readOnlyHint=true, but the description adds valuable context by stating it is a read-only status check that does not create checkout links or collect payment. It also describes the follow-up workflow when billing blocks a launch, which is useful behavioral information beyond the annotations.

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

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

The description is three sentences, front-loaded with the primary use case, and every sentence adds value. It is concise without sacrificing needed behavioral and usage 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?

The description covers usage scenarios and next steps well, and an output schema exists so return values are defined. However, the lack of parameter semantics for format and onboardingAttemptId creates a notable gap in the agent's ability to fully utilize the tool, preventing a higher score.

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. However, it only implies artistId via 'one artist' and does not explain the format parameter (json vs summary) or the optional onboardingAttemptId. The agent is left without guidance on what these parameters do or when to use them.

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 exactly what the tool does: retrieves billing state, credit balance, promo limits, subscription status, and whether billing blocks launches for an artist. It also distinguishes from siblings by explicitly excluding campaign analytics and platform connection troubleshooting, 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?

Provides explicit when-to-use scenarios (billing state, credit balance, promo limits, subscription status) and a clear exclusion ('Do not use for campaign analytics or platform connection troubleshooting'). It also includes actionable guidance on what to do if billing blocks a launch, which is beyond simply stating usage.

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 correctly adds context without contradicting: it explains what each include flag toggles, mentions 'delivery/deployment blockers', and recommends format=summary after mutations. This is richer than a simple read-only note, though it could mention response format or any limits, which are covered by the output schema.

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

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

Three sentences, front-loaded with purpose, and every sentence carries actionable information. No filler or redundancy. It efficiently covers purpose, usage guidelines, and conditional recommendations.

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 tool with an output schema, the description is quite complete: it covers when to use, flag semantics, alternatives, and format preference. The only missing elements are definitions for analyticsDateRange and analyticsGranularity, which slightly reduce completeness given the tool's complexity.

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 must compensate. It explains includeAnalytics, includeDeploymentStatus, includeCountries, and format, and implicitly campaignId via 'one campaign.' However, it omits analyticsDateRange and analyticsGranularity, which are part of the schema but not described. This is a clear gap given the low schema coverage.

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 'Use this when the user wants full details for one campaign,' which clearly states the specific verb (get), resource (campaign), and scope (one campaign). It also differentiates from the sibling tool dynamoi_list_campaigns by explicitly excluding list functionality.

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 context ('full details for one campaign'), explicit alternatives ('use dynamoi_list_campaigns instead'), and conditional guidance for flag settings (includeAnalytics, includeDeploymentStatus, includeCountries) and format preference after mutations. This leaves no ambiguity about when to choose 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 description adds value by clarifying it 'validates readiness ... without creating a campaign' and reinforcing the non-mutating nature. It does not contradict annotations and provides useful context about its role as a pre-flight check.

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 clear purpose: when to use, what it does, and what not to use. No redundancy and front-loaded with the most critical information.

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

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

The tool is complex with 11 params and an output schema, but the description covers the primary use case and safety constraints. Return values are documented in the output schema, so the description doesn't need to explain them. It misses nothing essential for an agent to decide when to invoke it, though parameter guidance 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 provides no detail about the 11 parameters. It only mentions 'proposed inputs' generically, failing to explain which fields matter, required fields, or how targeting parameters relate. The description does not compensate for the schema's lack of descriptions.

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 it validates readiness and targeting before campaign launch, distinguishing it from launch_campaign and other sibling tools. It uses a specific verb ('validates') and names the resource context accurately.

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 ('planning a campaign' and 'before dynamoi_launch_campaign') and provides a clear exclusion ('Do not use this to create or mutate campaigns'). This gives the agent unambiguous direction for tool selection.

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 read-only and non-destructive. The description adds context about the returned status and the polling correlation behavior, which is beyond the annotations. No 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?

Three sentences; first states purpose, second adds polling context, third provides exclusions. 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?

The description covers the main use cases and exclusions, and with an output schema present, return values are handled. However, the required artistId is left unexplained, and the format parameter is ignored, so it's not 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?

The description explains the purpose of onboardingAttemptId and onboardingFlow (returned from connection-start flow) but provides no meaning for the required artistId or format parameter. With 0% schema coverage in the description, this leaves a 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 opens with a clear verb and resource: 'know whether Spotify, Meta, or YouTube are connected' and 'what setup steps still block launches.' This distinguishes it from sibling tools like billing or 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 explicitly states when to use (status checks, polling after connection-start flow) and when not to use ('Do not use for detailed billing questions,' 'Never use to personalize generic advice'). It names the correlation parameters but does not direct to alternative tools, so it's just shy of full 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. The description adds helpful behavioral context by specifying that analytics and artist settings are optional flags, and by instructing the agent to lead with the public URL and avoid exposing internal IDs. 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, each earning its place: use case, optional flags, and output expectations. Front-loaded and free of 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?

Annotations and output schema reduce the burden, but the tool has 9 optional-looking parameters and no required fields. The description gives output expectations but omits any guidance on parameter combinations or how the tool resolves which Smart Link to return, leaving a meaningful completeness 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?

With 0% schema description coverage, the description must explain parameters but only covers includeAnalytics and includeArtistSettings. It does not clarify how to select the target Smart Link (playLinkId vs spotifyUrl vs artistId) or what format, dateRange, granularity, and includeBreakdowns do, leaving the agent guessing for 7 of 9 parameters.

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 retrieves full details for a single free Smart Link and enumerates the specific data points included (release, Spotify URL, public URL, status, theme source, next actions). This differentiates it from sibling tools like list_smart_links or 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?

It explicitly says 'Use this when the user wants full details for one free Smart Link', giving a clear use case. It lacks exclusionary guidance or named alternatives, but the context is sufficient to distinguish from the obvious siblings.

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 signal write/destructive behavior, but the description adds valuable operational details: ads may not be live until delivery state ACTIVE, demo/review launches can omit certain optional fields with inferred defaults, and placeholders should not be invented. This goes beyond the annotation booleans and gives the agent actionable safety information.

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 fairly long but every sentence carries operational weight, and the key usage conditions are front-loaded. It is structured in a logical order: when to use, behavioral caveats, special case handling, and post-use behavior, with no redundant 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?

Given the tool's complexity (17 params, nested objects, side effects), the description covers essential context: real vs. simulated campaigns, delivery state expectations, and demo-specific parameter handling. Since an output schema exists, return value details are not needed. The main gap is systematic parameter coverage, but the schema and special-case guidance make the tool usable.

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 description adds meaningful guidance for spotifyUrl and endDate (when to omit them and not invent placeholders), and it references artist, content title, budget, countries, and media assets which map to several parameters. However, with 17 parameters and 0% schema description coverage, many parameters (e.g., budgetSplits, locationTargets, adCopy) are left for the agent to interpret from their names and schema enums 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 uses a specific verb and resource ('create a new Smart Campaign or YouTube Campaign and start the launch workflow'), clearly distinguishing this from sibling tools like update_campaign or get_campaign. It also explicitly excludes use for recommendations or previews, reinforcing its unique purpose.

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 conditions ('when the user explicitly wants to create a new Smart Campaign or YouTube Campaign') and when-not-to-use ('Do not use this for recommendations or previews'). It also provides guidance on post-success behavior (answer from returned details, don't chain tools), which is practical usage direction.

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 valuable behavioral context: what fields are returned, the empty-result meaning (brand-new user), and the required routing to account overview. This goes beyond the annotations.

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

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

The description is longer than typical but every sentence adds guidance: usage, exclusions, artistId semantics, and empty-result handling. It is front-loaded with 'Use this when...' and contains no fluff, though it could be split into shorter sentences for readability.

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

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

With an output schema present, return-value explanation is unnecessary. The description covers purpose, alternatives, parameter nuance, and edge-case handling (empty result). It does not mention pagination defaults or format options, but those are inferable from the schema. Overall it is quite complete for the tool's complexity.

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 explains artistId ('Pass artistId when you need the full profile/readiness details'), but limit, cursor, and format are not addressed. Since it explains one key parameter but leaves others implicit, it partially compensates but not fully.

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 lists artists/YouTube channels managed, along with billing status, active campaign count, and role. It explicitly differentiates from sibling tools by saying 'Do not use this for campaign details; use dynamoi_list_campaigns or dynamoi_get_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?

Provides explicit when-to-use ('when the user wants to see which artists or YouTube channels they manage'), when to pass artistId, and names alternatives for campaigns. Also gives a never-use condition for generic social-media advice and routes empty results to dynamoi_get_account_overview.

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 the behavioral nuance that Smart Campaign and YouTube catalogs differ, but it does not disclose behaviors like pagination limits or how query/filtering affects results. Overall, it adds modest value beyond 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 no wasted words: use case, mandatory parameter, and exclusion. Each sentence carries essential guidance and the description is properly front-loaded with the primary 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?

The core use case and required parameter are covered, and an output schema exists for return values. However, with five parameters and 0% schema coverage, the description leaves optional params like query, limit, cursor, and format unexplained, making the tool only partially self-sufficient.

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

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

Schema description coverage is 0%, so the description must compensate. It only explains campaignType (which is already clear from the schema's enum and required flag). No semantics are provided for limit, query, cursor, or format, leaving their purpose ambiguous for an agent.

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 this tool lists countries for targeting in Smart Campaigns or YouTube campaigns, using a specific verb and resource. It distinguishes itself from siblings by focusing on country catalogs and explicitly warns against using it for generic country marketing advice.

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 ('Use this when the user asks which countries they can target') and when-not-to-use ('Do not use this for generic country marketing advice'). It also instructs to always pass campaignType because catalogs differ, which is actionable and context-rich.

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 readOnlyHint and destructiveHint, so the safety profile is clear. The description adds some behavioral context (scope to one artist, filterability by type/status, and a policy note to never use for generic marketing advice), but it does not disclose behaviors like pagination semantics, default formatting, or ordering, beyond what the schema enums imply.

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 sentences, front-loaded with the primary use case, and every sentence adds meaningful guidance. It avoids fluff and repetition, and the imperatives are clear.

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 and annotations, the description provides enough context to understand when to use it, what it does, and how it relates to alternatives. It could be slightly more complete by explaining pagination parameters, but overall it covers the essential operational context.

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

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

Schema description coverage is 0%, so the description must compensate. It only indirectly mentions 'status' and 'type' as filters, and 'artist' as the scope, but leaves limit, cursor, and format entirely unexplained. With six parameters and no schema descriptions, this 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 that the tool 'browse[s] campaigns for one artist, optionally filtered by type or status,' using a specific verb and resource. It also distinguishes itself from the sibling tool dynamoi_get_campaign by explicitly saying not to use it for a single campaign deep dive.

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 provides explicit when-to-use and when-not-to-use guidance. It says to use it for browsing campaigns for one artist, tells the agent not to use it for a single campaign deep dive (use dynamoi_get_campaign instead), and instructs to route via dynamoi_get_account_overview if the user has no artists.

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 safe-read nature is established. The description adds useful context that assets are reusable campaign media and that includeUrls returns public-safe URLs, which goes beyond the annotations. It doesn't detail pagination, but that is a minor gap given the annotations cover the 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?

The description is three concise sentences with no fluff. It is front-loaded with the primary use case, followed by an exclusion and parameter-specific guidance. Every sentence adds value and the structure is clean.

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 has moderate complexity (5 parameters, no schema descriptions, output schema present), the description covers purpose, exclusions, and two key parameters. Missing artistId and pagination details, but the output schema and annotations fill some gaps. It is sufficiently complete for an agent to select and invoke this read-only list tool 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?

Schema description coverage is 0%, so the description must compensate. It explains format (json for asset IDs) and includeUrls (for public-safe URLs), but leaves artistId, limit, and cursor unexplained. This provides partial compensation, but not full coverage for all five parameters.

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 lists uploaded images/videos for reuse in campaign launches. It distinguishes itself from siblings like list_campaigns and list_artists by explicitly focusing on media assets, with a specific verb and resource.

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 ('when the user wants to choose from uploaded images or videos that can be reused in a campaign launch') and when not to use ('Do not use this when the user only wants campaign status or analytics'). It also provides conditional guidance for format and includeUrls parameters, making the selection criteria very clear.

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; the description adds output scope (release title, public URL, publish/claim/render states, theme) and presentation guidance (show public URLs, avoid internal IDs). No side effects are disclosed, but the read-only safety profile is reinforced and useful output context is provided.

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 serving a distinct purpose: primary use case, exclusion with alternative, and fallback handling. It is front-loaded, concise, and contains no redundant phrases.

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 and readOnly annotations, the description covers main usage context, exclusions, and fallback behavior. It provides enough for an agent to select and invoke the tool correctly, while output structure is already defined by the schema.

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

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

Schema has 8 parameters with 0% description coverage. The description only implicitly clarifies artistId ('for one artist') and omits meanings for limit, cursor, query, format, and status filters. Parameter names and enums give some inference, but the description fails to compensate for the low coverage.

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 'list free Smart Links for one artist' with a specific verb and resource scope, and explicitly distinguishes from dynamoi_list_campaigns for paid campaigns. This provides a precise purpose aligned with the title and differentiates it from 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 explicitly states when to use ('when the user wants to list free Smart Links for one artist') and when not ('Do not use this for paid campaign lists'), naming the alternative tool. It also provides fallback actions when empty with connected Spotify, making usage guidance thorough.

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 nature is covered. The description adds value by specifying it is a 'visual preview' and explicitly listing non-actions (create, publish, update, promote), which provides extra context beyond the annotations. No contradiction exists.

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-loaded with concrete usage guidance, and avoids repetition of schema or annotation information. Every sentence earns its place, and the exclusionary list is concise.

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 annotations covering safety, the description is largely complete for a read-only preview tool. However, the lack of parameter semantics is a notable gap, and the description could be more complete for a tool that takes user input. Given the tool's low complexity, a score of 3 is appropriate.

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 has 0% description coverage, and the description does not explain the two optional parameters (artistName, releaseTitle) at all. While the parameter names are somewhat self-explanatory, the description fails to clarify how they affect the preview or whether they are required for customization, leaving 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 states the tool's specific purpose: previewing available Smart Link themes. It uses a clear verb ('preview') and resource ('Smart Link themes'), and distinguishes it from creating, updating, publishing, or promoting Smart Links, which differentiates it from sibling 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?

The description provides explicit when-to-use scenarios: when the user asks what Dynamoi Smart Link pages look like, wants to compare themes, or wants to preview themes before creating/updating a free Smart Link. It also explicitly states what it does not do (create/publish/update/promote), giving clear exclusions without naming alternatives directly but making the boundary obvious.

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 nature is covered. The description adds valuable behavioral context beyond annotations: it warns against treating 'no records found' as terminal for new users and suggests creating a first artist hub. This is useful edge-case handling not evident from annotations.

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

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

Three sentences, front-loaded with the primary use case, then exclusions, then edge-case handling. Every sentence carries meaningful guidance with no filler or repetition of schema details.

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 search tool with an output schema and good annotations, the description covers the core workflow, exclusions, and a specific empty-result scenario. It does not explain pagination or return format, but the output schema exists and the cursor/format parameters are self-explanatory enough. The missing parameter explanations slightly reduce completeness.

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 does not. While the description mentions searchable entities (artist, release, campaign, smart link) and hints at the 'type' parameter, it fails to explain parameters like query, limit, cursor, format, artistId, or includeArchived. The enums in the schema help, but the description adds little semantic value beyond the bare 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 clearly states the tool's purpose: searching for artist, release, campaign, or smart link records when the exact record is unknown. It distinguishes from list/get siblings by framing the use case ('do not yet know the exact record') and explicitly says not to use it for analytics or billing once the target is known.

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 usage guidance: use when user mentions an entity lacking a known ID, avoid for analytics/billing once target is known. It also gives a specific alternative action for empty results on new users, referencing a sibling tool (dynamoi_create_smart_links_from_spotify_artist), which 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?

The description discloses critical behaviors beyond annotations: it returns a signed OAuth URL, may navigate the user through a Page/Instagram selection step, and handles billing errors with specific return values. It even specifies the retry semantics for transient issues, which aligns with the idempotentHint=true annotation.

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 compact paragraph that front-loads the primary purpose and then flows through the expected behavior, error paths, and follow-up. No wasted words; every sentence adds essential operational detail.

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 tool's workflow thoroughly, including prerequisites, error states, and post-link polling. It leverages the existing output schema by not restating return structure. However, the complete omission of parameter semantics prevents a perfect score, even though that is partly addressed in the parameter dimension.

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%, yet the description does not explain any of the three parameters (artistId, format, userIntentSummary). It only mentions a returned onboardingAttemptId, which is not a param. The agent is left without guidance on what values to provide, which is a serious gap for correct invocation.

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: initiating Meta connection for Spotify Smart Campaigns and returning a signed OAuth URL. It distinguishes itself from sibling tools like dynamoi_start_youtube_channel_link by explicitly targeting Meta and describing the flow.

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 states when to use ('when billing is active and the user is ready to connect Meta'), and provides error cases with guidance (retry for transient billing check failures). It also directs to a follow-up polling tool, giving clear usage context.

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 discloses the OAuth flow: it returns a URL, the user returns to Dynamoi, and the assistant must poll for status. This supplements the annotations (idempotentHint, openWorldHint) with concrete next steps and auth context. 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?

Three sentences, front-loaded with the use case, then the output, then the follow-up. No redundant information.

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

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

The overall OAuth flow is well explained, including the need to poll for connection status. However, the lack of parameter semantics for format and userIntentSummary means the description isn't fully complete for correct invocation, though the schema provides some structure.

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%, and the description only mentions 'artist' in passing without mapping to the artistId parameter. It does not explain the format enum or userIntentSummary field, leaving the agent to guess their purpose.

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: linking a YouTube channel to a Dynamoi artist via a Google OAuth URL. It specifies the resource (YouTube channel, artist) and the action (start/link), distinguishing it from sibling tools like start_meta_connection.

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 says 'Use this when the user is ready to link a YouTube channel to one Dynamoi artist from chat,' providing a clear trigger condition. It also directs the subsequent polling of dynamoi_get_platform_status, but doesn't explicitly list alternative tools for other platforms, though the platform-specific wording implies that.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description doesn't need to restate that. It adds specific behavioral context by noting 'this changes live campaign workflow state or external campaign settings,' which explains the nature of the destructive mutation beyond the binary hints.

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

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

The description is two sentences, front-loaded, and wastes no words. It delivers the key usage instructions and exclusions efficiently.

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 having an output schema and annotations, the description is insufficient for a complex 12-parameter mutation tool. It does not explain optimistic concurrency controls (expectedCurrent*), required consents, or the meaning of authorizeAutomaticDailyFunding, leaving substantial gaps in operational guidance.

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 only 8% schema description coverage, the description must compensate, but it only covers the action parameter values and mentions budget/end date. It fails to explain other critical parameters like expectedCurrentStatus, expectedCurrentEndDate, authorizeAutomaticDailyFunding, and consent fields, leaving the agent underinformed for a 12-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 clearly states the tool's purpose: 'pause, resume, or update the budget/end date for an existing campaign.' It uses a specific verb and resource, and implicitly distinguishes from siblings like get_campaign (read-only) and launch_campaign (create new).

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 says 'Use this when the user explicitly wants...' and provides a clear exclusion: 'Do not use this for inspection-only questions.' It does not name the alternative tool directly, but the context makes it evident that inspection belongs to get_campaign or similar read-only 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 indicate this is a non-read-only, idempotent, destructive operation. The description adds valuable context beyond those hints by noting that updates may queue background rendering and that public availability is artist-wide. It does not contradict the annotations.

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

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

The description is three concise sentences, front-loaded with the primary use case and containing no fluff. Every sentence contributes meaning, including the action enum guidance and the important caveat about not publishing/unpublishing.

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 core purpose and provides some side-effect context, and an output schema is present. However, with 11 parameters and two distinct actions, the lack of per-action parameter mapping makes the description insufficient for full contextual understanding. The description is adequate for basic orientation but not complete for complex 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?

With 0% schema description coverage, the description must explain parameters, but it only clarifies the 'action' enum and broadly references description/theme/pixel fields. It does not explain the roles of playLinkId, artistId, clientRequestId, expectedUpdatedAt, userIntentSummary, googleAdsConversionId, or which parameters are needed for each action. Significant gaps remain.

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: changing a Smart Link's public description or updating artist-level theme/pixel settings. It uses specific verbs and resource names, and distinguishes this from publication toggling by clarifying it does not publish/unpublish individual links.

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 begins with 'Use this when...' and explicitly identifies two supported actions. It also provides an exclusion by stating the tool does not publish or unpublish individual links. It does not name an alternative sibling tool, but the context is clear enough for most use 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. The description adds context that it returns a full record for citation, which is useful but not a major behavioral disclosure beyond what annotations provide. 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?

Two concise sentences, front-loaded with the tool's purpose and immediately followed by the id format specification. Every sentence earns its place with no fluff.

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 low complexity, the presence of an output schema, and annotations covering safety, the description is largely complete. It covers the input contract and purpose, but could be slightly more explicit about its relationship to sibling getters for full contextual completeness.

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 compensates well by explaining the id parameter's format, source (from search), and purpose. This adds significant meaning beyond the bare 'id' string in the schema, though it could additionally note potential validation requirements.

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 tool as a fetch contract that returns the full record for a given id from search. It specifies the exact id format ('artist:<uuid>', 'campaign:<uuid>', 'smartlink:<uuid>') and distinguishes it from the sibling search tool by focusing on retrieval of full records.

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 states the prerequisite that the id must come from search and enumerates the accepted id formats, guiding when to use the tool. However, it does not mention alternative sibling getters like dynamoi_get_campaign or dynamoi_get_smart_link, so there's a slight gap in when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral context (that it's a 'search contract' for citation use), but does not disclose limitations, pagination, or other traits beyond what annotations and schema already provide.

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

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

Two sentences, front-loaded with the core purpose, and no redundant filler. Every word 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 tool is simple with one parameter, has an output schema, and annotations cover safety. The description provides the when/where/alternatives effectively. No additional information is necessary for the agent to use 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?

Schema description coverage is 0%, and the description does not compensate for the single 'query' parameter. It doesn't explain what the query should contain (e.g., search terms, format) or how matching works, leaving the agent to infer from the tool name and general search semantics.

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

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

The description uses a specific verb 'Returns' and clearly identifies the resources (Dynamoi artists, campaigns, Smart Links). It also distinguishes itself from the sibling tool dynamoi_search by specifying the context (deep-research session).

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 states when to use this tool ('OpenAI ChatGPT Deep Research / Connectors') and provides a direct alternative for regular ChatGPT chat ('use dynamoi_search instead'). This clearly differentiates from siblings.

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