Splice docs

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is fully covered. The description adds that the output is markdown and that the pricing doc carries a live/dynamic model table, which is useful context, but nothing about caching, freshness of other docs, or auth requirements.

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

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

A single tight sentence with the payload type ('markdown') and the valid ids front-loaded; no filler. The colon-and-list construction is slightly telegraphic but easy to parse.

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-param, no-output-schema read tool, the description covers what comes back (markdown) and the full space of valid ids. The main gap is the unresolved relationship with get_pricing and search_docs, which the agent must infer from sibling names alone.

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

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

Schema coverage is 100% and the single 'id' parameter is an enum with a description, so the schema fully documents it. The description restates the same four ids, which is redundant rather than additive; baseline 3 applies.

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

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

States the resource (a Splice agent doc) and the return format (markdown), and enumerates the four retrievable ids, so the agent knows exactly what this fetches. It does not differentiate from the get_pricing sibling, which overlaps on the 'pricing' id, leaving slight ambiguity about which to call for pricing data.

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

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

No when-to-use or when-not guidance, and no routing to alternatives such as search_docs for topic discovery or get_pricing for pricing. The overlap with get_pricing is acknowledged only indirectly by noting the pricing doc contains the live model table.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds payload-level context by enumerating the categories of pricing content returned, which is useful for a tool whose annotations say nothing about output. It omits any note on freshness/currency of prices or auth requirements, so it is not fully rich.

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

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

Two short sentences with zero filler; the content scope is front-loaded and the sibling routing is last, which is the right ordering. Every clause carries information.

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

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

With no parameters and no output schema, the description carries the burden of describing the return payload, and it does enumerate the categories covered. Minor gap: it does not say anything about the shape or freshness of the pricing data, but for a no-arg read-only info tool this is close to 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 tool takes zero parameters, so the baseline is 4 per the rubric. The description correctly adds no parameter talk, and none is needed since the schema is empty and fully covered.

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 exactly what the tool returns (credit packs, sign-up credits, payment methods, the definition of a credit) and explicitly distinguishes itself from the sibling that handles the other pricing case: 'For per-model prices use list_models.' An agent can pick between get_pricing and list_models without opening either schema.

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

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

It gives a clear routing rule to the alternative (list_models for per-model prices), which covers the most likely confusion given the sibling set. It does not state general preconditions or other exclusions (e.g., how it relates to get_doc/search_docs), so it stops short of full when/when-not coverage.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value by disclosing the returned content (model, prompt, settings) and the downstream generate/url affordances, which annotations do not cover.

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

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

Two short sentences with no filler; the resource and payload are front-loaded and the follow-up action is tacked on compactly. Every clause carries information.

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

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

With no output schema, the description steps in to describe the return payload and how to consume it, which is the main thing an agent needs. It does not mention error behavior for an unknown slug, but for a simple read tool this is close to complete.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema, including its provenance ('from list_templates'). The description's 'by slug or id' restates what the schema already says, so there is no material addition.

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

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

States a specific verb and resource ('One public template by slug or id') plus the shape of what comes back ('generation payload (model, prompt, settings)'). An agent can immediately distinguish it from list_templates, which returns many.

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

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

It names downstream actions ('run it with the product server's generate tools, or open its url in Splice'), which is workflow guidance rather than when-to-use guidance. It never states when to prefer this over list_templates or any sibling, so usage is only implied.

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

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

Annotations already cover read-only/idempotent/non-destructive, so the bar is lower, and the description adds real context: the credit-to-dollar conversion, the meaning of the unit values (per_generation, per_second, usage), and variant-per-resolution behavior. This explains what the returned numbers mean, though it omits any pagination or rate-limit behavior.

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

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

Dense but front-loaded: it leads with the core action and pricing, then defines units. The pricing.json cross-reference earns its place as a provenance note. Minor density but no wasted 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 no output schema, the description bears the burden of explaining returns and does so reasonably for a simple list tool by clarifying units and variants. Combined with the fully-covered input schema and safety annotations, an agent has enough to call 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 coverage is 100% and the sole 'type' parameter is fully documented in the schema (including enums and 'Omit for all'). The description adds no parameter-specific detail, so the schema-vs-description baseline of 3 is appropriate.

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

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

States a specific verb+resource (list models) and enriches it with what the listing contains (standard price in credits, units, variants). It's an unambiguous purpose, but it never differentiates from the sibling get_pricing, which appears to overlap in domain.

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

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

There is no explicit when-to-use guidance. The description explains the data returned rather than when to call it or how it differs from get_pricing, leaving the agent to guess whether it should call this or the pricing sibling.

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 readOnly/idempotent/non-destructive, so the bar is lower. The description adds real value by disclosing the return shape (summaries, not payloads) and pointing to the tool that returns the payload, though it says nothing about pagination behavior beyond the schema's offset/limit.

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

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

Two tight sentences with zero filler; the resource definition comes first and the sibling routing is front-loaded in the second clause.

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, zero-required-parameter list tool with no output schema, the description covers what it returns (summaries) and where to go for full payloads. Filter semantics rest on the schema, which is acceptable but leaves 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 60%, so the schema carries most parameter meaning. The description's enumeration of media kinds ('images, video, music and motion') loosely maps to the media_kind enum but omits 'voice' and never mentions query, category, limit or offset, so it adds only marginal detail.

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

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

Specific verb+resource (browse the public template library) with an explicit definition of what a template is ('curated model + prompt + settings recipes'). It also distinguishes itself from the sibling get_template by stating it returns summaries.

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 routes the agent to get_template when a full ready-to-run payload is needed rather than a summary. Clear use context, but no explicit when-not conditions and no guidance on combining query/category/media_kind filters.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is corpus scope and result form ('best-matching sections with their text'). It stops short of disclosing ranking/ordering or truncation behavior, which would matter for a search tool.

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

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

Three short sentences, front-loaded with what is searched before the routing hint. Every sentence carries information an agent needs; nothing is redundant with the title or 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 two-parameter search tool with no output schema, the description covers purpose, corpus, return form, and the sibling routing rule. Minor gap: no note on result ordering or how matching is ranked, which an agent might want when interpreting results.

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

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

Schema description coverage is 100%, so both 'query' and 'limit' are already documented in the schema, including example queries and the default of 5. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource (keyword search over Splice agent docs) and scopes the corpus explicitly (getting started, authentication, MCP servers, pricing). It also states the return shape (best-matching sections with text), so an agent can distinguish it from get_doc without opening either schema.

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

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

Explicitly names the alternative and the condition that selects it: 'Use get_doc for a whole document.' Combined with 'keyword search over the Splice agent docs', the agent knows to use this for targeted lookup and get_doc for full reads.

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