chartlink

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

The annotation only provides openWorldHint: false, so the description carries most of the behavioral transparency burden. It does this well by disclosing that the tool stops scheduled fetches and retains existing chart data, which clarifies the side-effect profile. It does not mention reversibility or return behavior, but for a simple detach operation this is reasonably transparent.

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 short sentences with no filler, and the primary behavior is front-loaded. Every word earns its place, making it easy for an agent to parse quickly.

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 one parameter and no output schema, the core behavior is conveyed effectively. However, the missing id semantics and lack of explicit usage guidance mean an agent would still need to infer the input and the appropriate scenario, making this only minimally viable.

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 input schema provides only a required string id with no description, and schema description coverage is 0%. The description never explains whether id refers to the chart, the data source, or something else, though the title implies it is the chart id. Since the description must compensate for the missing schema detail but does not, parameter semantics are 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 title 'Detach a chart's data source' and description 'Stops scheduled fetches; the chart keeps its current data' clearly identify the action, the resource, and the expected result. It is not tautological and effectively conveys that this is a non-destructive detach rather than a delete or replacement.

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 intended use case is implied by the description: use this tool to stop scheduled fetches while preserving current data. However, there is no explicit guidance about when to use this versus sibling tools like set_data_source or replace_asset_data, and no when-not-to-use conditions.

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 only include openWorldHint: false, which doesn't address behavior. The description fills this gap by disclosing that nothing is public until publish, that success means validation and rendering, that style comes from brand, and that there's a size limit (~100 KB of rows). This is rich behavioral context. However, it doesn't mention auth requirements or rate limits, which might be absent but not critical. A 4 is appropriate for the depth 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?

The description is a single dense paragraph, but it's well-structured and front-loaded with the primary purpose and the key behavioral note about inline preview. It efficiently includes examples and limits without fluff. However, it's somewhat long and might benefit from breaking into bullet points for clarity, which prevents a perfect 5.

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

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

For a complex tool with 7 parameters and nested objects, the description covers the main flow (create draft, iterate, publish), provides data format, limits, and alternatives. Since there's no output schema, it explains the response includes a preview and URL. It lacks details on error cases and exact output structure, but it's sufficient for an agent to use it correctly. A 4 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?

Schema description coverage is 100% as indicated, but the description adds significant meaning beyond the schema. It explains the data format (row-major, matching column order), the publish parameter's effect on URL liveness, and the template's merge behavior. It also clarifies the title alias for config.title.text. This goes beyond just repeating the schema, so a 4 is justified.

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 creates a draft asset and returns an inline preview image. The verb 'creates' and resource 'draft asset' are specific, and the mention of 'inline preview' and iteration via update_asset distinguishes it from siblings like update_asset and publish_asset.

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 (to create a draft and iterate) and when to use alternatives (publish with publish: true for one-call finalization, set_data_source for large datasets, replace_asset_data for appending chunks). It also warns about size limits, guiding the agent to choose better options for large data.

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?

With only openWorldHint:false in annotations, the description carries the behavioral disclosure burden. It adds valuable behavioral details: brands style assets they reference, the workspace default affects brand-less assets, and brands cannot inject data or text content. These go beyond the sparse annotation set.

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 main description is three concise sentences, front-loading the most important brand semantics before the create instruction and the style-only constraint. Every sentence earns its place with no repetition 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?

The description plus schema covers brand creation, application via slug, default-brand fallback, style-only restriction, and the token shape with resolution order. It does not explain the response format, but that is not required given no output schema and the tool's relatively straightforward create action.

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 75%, so most parameters are documented in the schema itself. The main description adds little parameter-specific detail beyond the style-only intent; the detailed tokens shape and resolution order live in the schema. The missing 'name' description is self-evident and not 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 exact action ('Create one'), the resource ('brand'), and the core purpose ('reusable style token set'). It also clearly separates brands from data-related operations by saying 'Style only: brands can never inject data or text content,' which distinguishes it from sibling tools that work with asset content.

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 explains when to create a brand ('Create one, then render any asset with brand: "<slug>"') and clarifies the default-brand behavior for assets without an explicit brand. It gives clear context but does not explicitly name alternatives like update_brand 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?

The description discloses key behaviors beyond the sparse annotations: the URL is checkout-only, no login is needed, credits are restricted to this workspace, and credits arrive quickly after payment. It also cross-references get_billing for verification, adding practical 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 short sentences, front-loading the primary return value before adding safety and timing details. Every sentence adds useful information with 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?

For a tool with one optional parameter and no output schema, the description is complete: it explains what the tool returns, the checkout behavior, the workspace restriction, and how to verify the resulting credits. No critical missing context is apparent.

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 fully documents the single parameter 'pack' with an enum and default, so the description does not need to add much. The description adds no pack-specific meaning beyond the schema, which matches the baseline for high 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 states a specific action and resource: it returns a URL that opens Paddle checkout for a credit pack. It clearly distinguishes this from edit-link or asset tools by emphasizing workspace-limited credit purchase.

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 clear context: the link is meant to be handed to a human, requires no login or account, and is safe to share because it only adds credits to this workspace. It does not explicitly name alternatives or say when not to use it, so it stops short of a 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?

The annotation (openWorldHint: false) is minimal und covers none of the safety profile, so the description carries the full burden. It discloses the auth model (no login), the write capability (republish), the harm limits (never delete, never spend credits), the credential handling ('secret is shown once'), and the link lifecycle (non-expiring, revocable via revoke_edit_link). This is rich behavioral context well beyond the 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?

Three sentences each carry distinct payloads: core function, scope constraints, and usage/lifecycle guidance. The primary function is front-loaded in the first sentence, and the title adds complementary framing without redundancy. Every clause earns its place — 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 1-param tool with no output schema and a sparse annotation, the description covers everything needed to invoke and deliver: what is returned (a URL), how to present it ('hand it to your human' in the title), when to offer it, what the link permits, and how it can later be revoked. No critical invocation information is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The schema's 'ast_...' description conveys only the format; the description adds domain meaning by clarifying the parameter identifies the specific chart whose tweak panel is opened. For a single-parameter tool, this implicit mapping of id → chart is sufficient added value to exceed baseline.

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

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

The description states a specific verb and resource: 'Returns a URL opening the visual tweak panel for ONE chart' with an explicit scope list (text, colors, spacing, label nudges). It clearly differentiates from siblings like revoke_edit_link (revocation) and update_asset (direct editing) by framing this as a no-login URL minting tool for a single chart. The title reinforces the function with plain language.

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 an explicit when-to-use directive in caps: 'OFFER THIS whenever the human's request is aesthetic fine-tuning', and contrasts it with the alternative 'nudge-by-nudge back-and-forth'. The boundary is sharpened by the scope statement ('never delete, never spend credits, nothing else in the workspace'), which tells the agent when the tool is too narrow/too broad. The revocation counterpart is named for the link lifecycle.

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 flag destructive behavior, and the description adds valuable context: the delete is soft, reversible via the REST API, and affects embeds. It could also mention permission requirements or whether the asset remains visible in listings, but the key behavioral traits are disclosed.

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

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

Two short sentences carry all the essential information: the effect on embeds and the restore path. There is no filler, and the most important behavioral facts are 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 simple one-parameter soft-delete operation, the description is complete enough: it covers the observable effect, reversibility, and the restore mechanism. The lack of an output schema is acceptable for a delete action, though a note on permissions or when to prefer unpublish_asset would strengthen it.

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 input schema has a single required id with zero description coverage, and the tool description does not explain how id is used or what kind of asset identifier is expected. The parameter name is fairly self-evident, but the description does not compensate for the missing schema documentation.

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 the specific operation (soft-delete) and resource (asset), and clarifies the observable effect ('Embeds go dark') plus the recovery path. The title and description together clearly distinguish this from a permanent delete.

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

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

No guidance on when to use delete_asset versus sibling tools such as unpublish_asset, update_asset, or duplicate_asset. It describes the operation but not the conditions, prerequisites, or exclusions that should drive 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?

The description adds some behavioral context beyond annotations: a new id and new embed URLs are created. However, it doesn't disclose whether the original asset is modified, whether the duplicate is unpublished until explicitly published, or any permission requirements. The annotation openWorldHint=false doesn't contradict this, but leaves room for more transparency.

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 short and front-loaded with the most important behavioral fact (new id, new embed URLs) followed by the primary use case. No filler exists, though the terse style contributes to the parameter-semantics gap. It earns its sentences.

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 three parameters, no output schema, and minimal annotations, the description leaves significant gaps. It doesn't explain which asset is duplicated, the role of brand/title, or the lifecycle of the new draft. An agent would need to rely on the tool schema or external knowledge to call this correctly, making the description incomplete 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 for the three parameters id, brand, and title. It only hints that 'rebranding' relates to brand/title; it never states that id is the source asset id, what brand does, or what title controls. This is insufficient for an agent to confidently populate parameters without extra inference.

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 title and description together make it clear this duplicates an asset into a new draft. The description 'New id, new embed URLs' and 'rebranding a chart' indicate the duplication outcome and intent, though it doesn't explicitly name a sibling or say 'duplicate' in the description, so it stops short of full differentiation.

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

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

The description gives a clear use case: 'useful for rebranding a chart for another audience.' This tells an agent when to reach for this tool, but it doesn't mention when not to use it or propose alternatives like create_asset or update_asset, so no exclusions are provided.

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 return shape '{ok, rows, published, error}' and clarifies that it is a one-off fetch rather than a schedule change. However, it does not explain side effects, failure semantics, error content, or access requirements. With only openWorldHint=false as an annotation, the description carries more responsibility and only partially meets it.

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

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

The description is compact, front-loaded, and contains no filler. Both sentences earn their place: one states the action, the other the return contract.

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 a single parameter, no output schema, and minimal annotations, the description provides the return shape and scheduling context. However, it omits the meaning of the id parameter and the nature/format of the error field, leaving visible gaps for a caller.

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

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

Schema description coverage is 0%, and the description never explains what the required id parameter refers to. The name and title imply it is likely a data source or chart id, but the description itself adds no meaning to the schema's bare property definition.

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 and title clearly state the tool's action: 'Runs one fetch on top of the schedule' and 'Refresh a chart from its data source right now.' This differentiates it from related data-source tools like set_data_source or clear_data_source in practical terms, though it does not explicitly name any sibling tool.

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

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

The phrase 'on top of the schedule' implies this is for on-demand refreshes outside the normal schedule, but the description does not explicitly state when to use this tool versus alternatives. No exclusions or alternative tool names are provided.

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 convey read-only, idempotent, and closed-world behavior effectively. The description adds real behavioral content by explaining that includePreview=true returns an inline PNG of the current draft)Skip and that the response is the full asset envelope. This supplements the annotations rather than 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?

The description is compact and front-loads the core behavior, with the conditional PNG behavior appended in the second sentence. No filler exists, though the phrase 'full asset envelope' is slightly cryptic and could be expressed more plainly.

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 a simple read-by-id operation with strong annotations, so it is callable, but the lack of an output schema and the vague 'full asset envelope' leaves the expected response shape underspecified. includeData remains unexplained, and the draft-state limitation is not reinforced in the description, creating a moderate 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?

Schema description coverage is only 33%, so the description must compensate. It meaningfully explains includePreview, but includeData is left undocumented in both schema and description, and id is only given its 'ast_' prefix. Partial compensation with a clear remaining 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 title states the verb and resource ('Get one asset') plus the draft-state qualifier, and the description clarifies it returns the full asset envelope with an optional PNG preview. It is clear enough to distinguish from list_assets, though it does not explicitly contrast with other getter-style 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?

No explicit when-to-use or alternative guidance is provided. The description does not say when to prefer get_asset over list_assets or get_spec_schema, and the draft-state scoping appears only in the title rather than in the tool description, leaving selection 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 and idempotentHint, so the safety profile is covered. The description adds valuable context: hosting is free, one credit permanently makes a chart premium, and updates are never metered, clarifying that the query is a status lookup and that usage doesn't consume credits. It doesn't mention rate limits or response details, but the annotation coverage lowers the bar.

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

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

The description is concise: three sentences, no filler, and compact coverage of the credit model. However, the first sentence is background rather than tool behavior, and an explicit statement of what get_billing returns would make it better 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?

With no parameters and no output schema, the description could be complete by stating that the tool returns the current credit balance and asset cap. The title does this, but the description itself never names the output or clarifies whether balance is in credits or another unit. It is adequate but has a clear 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?

The tool has zero parameters, so the baseline is 4. The description meaningfully explains what credits are and how they are consumed, which helps an agent interpret any returned billing data.

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 name and title clearly identify a read-only query for the workspace's credit balance and asset cap, and the description adds useful semantics about what a credit does. However, the description itself never explicitly states that calling this tool returns the balance/cap; it leaves that to the title and name.

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 no explicit guidance on when to use get_billing versus related tools like create_checkout_link or upgrade_to_premium. The credit explanation implies it may be used before purchasing, but there is no stated when-to-use or when-not-to-use condition.

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 read-only, idempotent, and not open-world. The description adds meaningful behavioral context: the defaults represent the complete effective config when nothing is set, and the merge order (brand first, then chart config) is disclosed. It also clarifies that the response contains multiple parts, not just a 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?

The description is two sentences, front-loaded with the return payload and then the usage rule. The parenthetical about defaults ('every font, padding, color') and merge order earns its place because it clarifies a non-obvious behavior without padding.

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

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

For a single-parameter, read-only, idempotent tool with no output schema, the description fully explains what comes back and how to use it. Nothing essential is missing: the schema, data schema, examples, defaults, merge semantics, and when to call it are all covered.

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 single parameter 'type' has 100% schema description coverage already ('e.g. "line"'). The description uses the parameter contextually as the asset type, but does not add new format, enumeration, or validation details beyond what the input schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Returns') and a specific resource: the JSON Schema for the type's config, the data schema, two worked examples, and defaults. It clearly differentiates itself from create_asset by positioning this tool as the prerequisite read before first asset creation.

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 it: 'Read this before your first create_asset of a given type.' It also tells the agent to 'read a baseline value from defaults instead of guessing it,' giving an actionable rule for applying the returned defaults.

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?

Read-only and idempotent behavior are already declared by annotations, and the description adds useful disclosure that returned rows are elided and full content requires get_asset. This goes beyond the 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?

Two short sentences carry both the core behavior and the routing to get_asset, with the list behavior front-loaded. No filler or redundant restatement of the tool name.

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

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

For a simple, zero-required-parameter list tool with read-only and idempotent annotations, the description is largely sufficient: filtering is noted, elision is disclosed, and the full-body alternative is named. The lack of an output schema makes a bit more return-format detail desirable, but the schema and annotations cover the essentials.

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 only 20% (only 'search' is described), so the description needed to compensate for type, status, limit, and offset. 'Filterable list' is the only parameter-relevant guidance and it does not explain which fields filter or how the enum behaves.

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

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

The description identifies a filterable list operation and distinguishes it from get_asset by noting that rows elide config/data. However, it relies on the tool name and title for the explicit resource ('assets'), so it is clear but slightly less self-contained than a fully specified statement.

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 clear routing guidance: use this tool for a filtered list summary and get_asset when full bodies are needed. It does not spell out when to prefer other list siblings (e.g., list_asset_types, list_brands), so it stops short of fully explicit when-not 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 and idempotentHint, so the description does not need to restate safe behavior. It does add one useful behavioral detail: the result includes links to per-type schemas. Still, it says nothing about completeness, ordering, or response shape, though for a simple list endpoint this is a minor gap.

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 sentence with no wasted words. It front-loads the core purpose and appends the one meaningful detail about per-type schema links.

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

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

For a zero-parameter, read-only, idempotent list tool with no output schema, the description is complete enough. It tells the agent what will be returned (chart/table types) and that each entry links to a schema, which is sufficient for correct 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?

The tool has zero parameters and 100% schema description coverage, so there are no parameter semantics left undocumented. The description wisely spends no space on inputs, and the baseline for a zero-parameter tool is appropriate.

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

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

The description uses a specific verb-resource pair: 'list' + 'asset types,' and further clarifies them as 'chart/table types you can create.' This clearly differentiates the tool from siblings like list_assets or list_templates, and the title reinforces the same meaning.

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

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

The phrase 'you can create' implies the tool is useful when deciding what asset types are available, likely before using create_asset. However, it does not explicitly state when to use this tool over alternatives such as list_templates or get_spec_schema, and no exclusions or routing guidance is provided.

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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context by clarifying that brands are style-only token sets scoped to the current config and that slug values are consumed by create_asset. 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?

Two short sentences, each earning its place: one defines the resource scope, the other explains the practical use. No filler, no repetition of schema or annotation 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?

Given zero parameters, readOnly/idempotent annotations, and a simple list operation, the description is nearly complete. It tells the agent what brands are, confirms they are scoped under the config, and explains how slugs are used downstream. The only minor gap is not explicitly describing the return shape, but that is not necessary for a straightforward list tool.

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

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

The tool has zero parameters, so the baseline is 4. The description adds meaning by explaining how the output (brand slugs) relates to a parameter on another tool (`brand` on create_asset), which is helpful context beyond the empty 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 title supplies the action ('List') and the description defines the resource as 'style-only token sets applied under your config,' making it clear this tool returns the available brands. It does not explicitly state 'returns all brands,' but the combination of title and description is sufficient to distinguish it from create_brand/update_brand.

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 directly tells the agent when to use this tool: to obtain a slug to pass as `brand` on create_asset. It does not explicitly discuss alternatives like create_brand or list_assets, but the contextual instruction is concrete and actionable.

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 read-only and idempotent behavior. The description adds meaningful behavioral detail: each result includes urls.png previews, chart type/title, required columns, and a human-facing gallery link. It also instructs the agent to 'show a few to your human', which is a useful interaction cue 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?

Every sentence carries useful information, but the phrasing is awkward and somewhat rambling—e.g., 'Published charts their owners offered' and 'urls.png' without clear context. The content could be tightened without losing meaning, so it's not a model of concise structure.

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

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

For a simple read-only list with one optional parameter and no output schema, the description covers what items contain, how to use the returned ids with create_asset, and the fallback that any chart id works. Missing details like pagination or ordering are minor at this complexity level.

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 single optional `type` parameter is fully described in the schema ('Only this asset type, e.g. "bar"'), so schema coverage is 100%. The description adds no parameter-level information, which is acceptable given the baseline of 3 when the schema does the heavy lifting.

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

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

The description clearly identifies the resource ('Published charts their owners offered as starting points') and the tool's purpose (start a new chart from one). It frames list_templates as a distinct template subset relative to the sibling list_assets, though it doesn't explicitly name that sibling or contrast them.

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 concrete downstream guidance: 'Then create_asset with template: <id> and your data — the whole design comes along.' It also notes that any chart id works as a template, signaling that this tool is not strictly required if you already have a chart id. No explicit when-not versus list_assets is given, but the use case is well implied.

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

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

The description discloses important behavioral traits: it makes the draft live, returns specific URLs, and explains how to use them on different platforms. It also mentions the pinned history behavior with '?v=N'. The annotation openWorldHint=false is minimal, but the description adds meaningful behavioral context beyond it. It doesn't mention side effects like whether it's reversible, but the core behavior is well covered.

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 concise and front-loaded with the main action ('Makes the draft live'). It then provides necessary usage details for the returned URLs. The title adds a clear summary. It's slightly dense but 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 publish action with 3 parameters and no output schema, the description covers the main behavior and return value usage. It doesn't explain what happens to the draft after publishing or whether it can be unpublished, but the sibling unpublish_asset implies reversibility. The description is complete enough for an agent to call the tool and handle the response.

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 only 33% (only premium has a description). The description doesn't explain the 'id' or 'note' parameters, but the schema already provides their names and types. The description adds context for 'premium' by mentioning paid credit and features, but doesn't fully compensate for the lack of descriptions on the other two parameters. Baseline 3 is appropriate since the schema covers the basics.

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 title and description clearly state the action: 'Makes the draft live' and 'snapshot a version and update every embed'. This distinguishes it from siblings like unpublish_asset and update_asset. The description also specifies the resource (asset) and the effect (publishing a draft).

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

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

The description implies when to use it: when you want to make a draft live. It doesn't explicitly state when not to use it or mention alternatives, but the sibling list includes unpublish_asset, which provides context. The description gives clear usage context for the returned URLs, which helps the agent know what to do after calling.

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?

With only openWorldHint=false in annotations, the description carries the full burden and delivers: it discloses that publish defaults to auto, that published assets republish immediately affecting every embed/PNG, that drafts stay draft, and it states size limits (2 MB asset cap, ~100 KB per call). These are critical behavioral traits not visible in 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?

The description is dense but tightly organized: core purpose first, then publish semantics, then limits and chunking alternative. Every sentence adds decision-relevant information; 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 mutation tool with nested params and no output schema, the description covers the operational context: size limits, chunking strategy, publish behavior, and an alternative tool for URL-based data. An agent has enough to invoke it correctly and avoid common failure modes.

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 only 40%, but the description compensates by explaining publish's default ('auto') and staging behavior, and by giving mode='append' its chunking purpose. It does not add semantic detail for note or id, but those are self-evident or already described in the schema, so the gap is acceptable.

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 title and description state a specific action ('replace data rows' / 'refreshing numbers') on a clear resource (asset data), and the description differentiates from set_data_source by naming it as the alternative for large datasets. The auto-republish behavior is front and center, so an agent knows exactly what the tool does.

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

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

The description gives explicit guidance on when to use this tool ('THE core flow for refreshing numbers'), when to stage instead (publish=false), when to chunk (larger datasets with mode append), and when to choose set_data_source instead (skip inline entirely for datasets up to full 2 MB). This is strong routing guidance beyond the schema.

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 immediate behavioral consequence of the operation ('URL stops working immediately'), which is useful. It does not cover side effects, idempotency, failure cases, or permission requirements, but the annotations provide no contradicting safety hints, so the score stays at a moderate level.

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

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

Two short sentences convey the effect and the way to find required parameters. There is no filler, and the most important behavioral fact 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 simple two-parameter mutation with no output schema, the description adequately covers the primary behavior and parameter sourcing. It does not mention error behavior or idempotency, but these are less critical given the tool's simplicity.

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 already documents tokenId well, and the description reinforces that tokenId values are obtained from create_edit_link or the list endpoint. For id, the description's URL pattern 'GET /assets/{id}/edit-links' implies id is an asset identifier, but this is not explicitly stated in the property description. At 50% schema coverage, the description partially compensates but could be more explicit.

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 operation as revoking an edit link and states the concrete effect ('URL stops working immediately'). It is distinguishable from the create_edit_link sibling by the action name and effect, though it does not explicitly contrast itself with any sibling.

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

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

The description implies when to use it: when you need to make an edit link stop working. It provides guidance on obtaining the required tokenId via GET /assets/{id}/edit-links, but it does not give explicit when-not-to-use guidance or mention alternatives.

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 are minimal (only openWorldHint false), so the description carries the full burden of behavioral disclosure. It discloses that fetches are immediate, that the tool returns an outcome to check (fetch.ok and fetch.error), that data is replaced and republished if published, and that refreshes are free. It also details column-matching rules (case-insensitive, space/underscore/hyphen interchangeable), which is critical for correct usage. No contradiction with annotations 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 well-structured: it opens with the core action and schedule, then explains data mapping rules, then immediate fetch behavior and error handling, and finally related-tool pointers. Every sentence adds value, and the main behavior is front-loaded. It is appropriately sized for the tool's complexity without unnecessary 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?

The description covers the essential aspects for an agent: what the tool does, the matching rules, immediate fetch and error handling, and how to verify the attachment (get_asset). It does not explicitly describe the full response structure (only mentions fetch.ok and fetch.error), and it does not discuss edge cases like invalid URLs or what happens when the chart is unpublished. Given the lack of an output schema, slightly more detail on the immediate return would improve completeness, but it is largely 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?

The schema covers only 50% of parameters (url and refresh have descriptions; id and format lack them). The description adds significant meaning for url (explains CSV/JSON formats and column-matching) and refresh (implies hourly/daily/weekly), and indirectly clarifies format via 'CSV or JSON'. However, it does not explicitly explain the id parameter or the exact syntax of format. The description compensates well for the coverage gap but leaves a couple of parameters under-explained.

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

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

The description clearly states the tool's purpose: making a chart self-updating by attaching a source URL that is fetched on a schedule. It explicitly names the resource (data source) and the action (set), and differentiates from siblings like clear_data_source and fetch_data_source. The core behavior is front-loaded, leaving no ambiguity about what the tool does.

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

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

The description gives clear context on when to use this tool (to attach a data source for self-updating) and mentions related tools for clearing (clear_data_source) and inspecting (get_asset). However, it does not explicitly state when to prefer alternatives like fetch_data_source (for a one-time fetch without attaching) or when not to use this tool. The usage guidance is implicit rather than explicit, but the context provided is strong enough for an agent to decide appropriately in most cases.

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

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

With only openWorldHint=false in annotations, the description carries most of the behavioral burden. It discloses real behavioral consequences: title-only reports cannot be acted on, detailed reports get fixed same-day, and submissions should be unique per distinct issue. This goes beyond the annotations and gives the agent useful expectations about how the feedback will be handled.

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 focused sentences with no filler. The most actionable guidance is front-loaded at the start, and each clause adds value: trigger conditions, per-issue cardinality, required detail level, and the outcome expectation.

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

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

For a simple submission tool with no output schema, the description covers the essential context: what to report, how to report it well, and what will happen afterward. It does not describe the submission response or explicitly state that the action is a write with no retrieval, but the schema and title cover most operational needs, leaving only minor gaps.

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 low at 25%, with only the description field explained. The tool description compensates by explaining what a good description must contain ('what you tried, what you expected, what happened') and by noting that title-only submissions are insufficient, which clarifies the title and description parameters. However, type and assetId receive no added semantic guidance beyond their schema names/enum, so the description only partially compensates for the coverage 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 uses a specific verb ('record'), names the resource ('gap' or issue), and clearly states the tool's purpose: capturing missing capabilities, schema problems, or doc errors for the owner to fix. The title reinforces this and distinguishes it from the sibling asset management tools, which all perform CRUD or asset operations.

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 when to use the tool ('if a capability is missing, a schema fights you, or docs are wrong') and adds clear usage constraints: one report per distinct issue and a substantive description is required. It does not mention alternatives because none exist among the siblings; the only slight gap is an explicit 'when not to use' instruction, though the positive triggers are quite strong.

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 flag destructiveHint=true, but the description adds useful specifics: unpublishing causes embeds and PNGs to return HTTP 410, and the effect lasts until republishing. This goes beyond generic destructiveness by clarifying the operation is reversible and what observable behavior occurs.

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 short sentence with no filler, and the key consequence is stated efficiently. It is less ideal because it leads with a side effect rather than an explicit action statement, but the title compensates for the missing verb.

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 one-parameter tool with destructiveHint already annotated, the description provides the essential behavioral context: the 410 status and reversibility. It does not explain the id parameter or mention permissions, but the operation is simple enough that the description is largely 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%, and the description does not explain what the required 'id' refers to beyond the schema's bare string type. The tool name and title imply it is an asset id, but the description itself adds no parameter meaning, creating a low-coverage 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 title 'Take an asset offline' and the tool name make the core action clear, and the description adds a concrete behavioral consequence: embeds and PNGs return 410 until republished. This distinguishes it from delete_asset and connects it to publish_asset, though the description itself never explicitly states 'unpublish this asset.'

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

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

The phrase 'until republished' implies a reversible lifecycle and hints that publish_asset is the complementary operation, which gives some usage context. However, it does not explicitly say when to choose unpublish_asset over delete_asset or any other alternative, nor does it state prerequisites.

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?

With only openWorldHint=false in annotations, the description carries the full behavioral burden and does so thoroughly. It discloses mutation behavior, deep-merge semantics, array replacement, null-clearing, config replacement for key removal, expectedVersion conflicts, 409 response recovery, and the non-publishing default. This goes well beyond the minimal annotation coverage.

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 carries functional weight. It front-loads the central merge semantics, then covers removal, data replacement, versioning, and publishing without repetition. The structure is efficient for a tool with this many behavioral nuances.

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 (9 parameters, nested objects, no output schema), the description is remarkably complete. It covers the key parameters, conflict handling, publishing behavior, and even preview output, leaving no critical gap an agent would need to resolve before invoking 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?

Schema coverage is only 44%, so the description must supply meaning, and it does. It explains that configPatch is deep-merged, config replaces the whole config and is the way to remove keys, data replaces rows wholesale, expectedVersion comes from the last envelope, and publish triggers publishing in the same call. These clarifications add real operational meaning beyond 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 title and description state a clear verb ('Update a draft') and resource, plus the two distinct modes (deep-merge patch vs. replace config). It also signals a concrete result ('returns an inline preview image'), making the tool's purpose unambiguous and distinguishable from siblings like publish_asset or update_brand.

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 when-to-use guidance: use configPatch for deep-merging, config to remove keys, and data to replace rows wholesale. It also directs the agent to pass publish: true or call publish_asset separately, and explains expectedVersion handling and 409 recovery, so an agent knows exactly how to select and sequence 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?

Discloses important behavioral traits beyond annotations: deep-merge rules (objects merge, arrays replace, null clears), immediate restyling of drafts, and deferred effect on published assets until next publish. This is exactly the kind of context an agent needs.

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

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

Three tight sentences with no filler. The most important behavioral rule (deep-merge semantics) is front-loaded, and every sentence adds value.

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

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

For a nested-parameter mutation tool with no output schema, the description covers the key operational concerns: merge semantics, side effects, and the version prerequisite. Minor gaps remain around acceptable idOrSlug formats and what the response contains, but these are not critical to invoking 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?

Schema description coverage is low (20%), but the description adds meaning for expectedVersion (sourced from list_brands) and clarifies tokens merge behavior. It does not add detail for name, isDefault, or idOrSlug, leaving those to the sparse schema.

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

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

States a specific action ('Update a brand') plus the distinctive token deep-merge behavior in title and description. This clearly separates it from sibling tools like create_brand or update_asset.

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

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

Gives clear contextual guidance by stating that expectedVersion must come from list_brands, which tells the agent the prerequisite call. It does not explicitly mention when to prefer create_brand, but the update semantics are clear enough.

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 several specific behavioral traits: same URLs, badge removed, 2400px PNG and SVG unlocked, custom branding applies, and idempotence. The title adds the credit cost, and there is no contradiction with the minimal 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 compact and front-loaded with the most important guarantee ('Same URLs, instantly rebranded'), then efficiently lists the unlocked benefits and idempotence. No wasted words.

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 one-parameter mutation tool with no output schema, the description covers purpose, effects, cost, and idempotence, which is nearly complete. The only minor gaps are the return shape and behavior when the chart is not trial-hosted.

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 single parameter `id` is fully documented in the schema with its 'ast_...' format, so the schema covers the meaning. The description does not add extra parameter-level detail, matching the baseline for 100% schema description 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 names a specific verb ('upgrade') and resource ('trial-hosted chart') and lists concrete outcomes such as badge removal and unlocking 2400px PNG/SVG. It does not explicitly distinguish from sibling tools like update_asset or publish_asset, so it stops short of a 5.

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

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

The title and description clearly imply the use case: upgrading a trial-hosted chart to premium, with a credit cost and idempotence for already-premium charts. No explicit alternatives or when-not-to-use conditions are given, but the context is clear enough for an agent.

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 idempotentHint=true, so the safety profile is covered. The description adds useful context beyond annotations: it explains that all writes are stamped with createdBy/updatedBy = key name, helping the agent understand why verifying the key first matters.

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 short, information-dense sentences. The most important behavioral cues—return value and 'call this first'—are front-loaded, and every clause adds value.

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

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

For a zero-parameter identity/auth check tool, the description is complete: it names the return payload, explains the non-destructive nature, and gives clear invocation guidance. No output schema is necessary given the simple return value described.

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

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

The tool has zero parameters, so there is no parameter meaning to clarify. The description appropriately focuses on return value and usage context instead, making the schema's empty properties object fully sufficient.

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 exactly what the tool does: 'Returns key name + workspace.' It is clearly distinguished from all sibling tools, which are CRUD/data operations rather than an authentication identity check. The title 'Verify your API key' reinforces the 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?

The description explicitly says 'Call this first,' giving a direct usage directive. It also labels itself as a non-destructive auth check, which makes it obvious that this is a safe preliminary step before mutation tools. Given the sibling list is all write/read operations with no other auth tool, no alternative comparison is needed.

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