Splice docs

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so safety is covered. The description adds behavior beyond that: the response is markdown, and the pricing doc embeds the live model table (useful for judging freshness/overlap with get_pricing).

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 short sentence with the key facts (one doc, markdown, valid ids) up front and no filler. It repeats the enum values from the schema, which is mild redundancy, and it is a fragment rather than a full sentence.

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, read-only, non-destructive tool with no output schema, the description covers output format and available docs adequately. The gap is routing: for a doc-lookup tool sitting beside get_pricing and search_docs, the absence of any disambiguation leaves the selection ambiguous.

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 enum already lists the valid ids, so the baseline would be 3. The description goes further by stating what one of those values yields ('pricing includes the live model table'), which helps the agent choose the id and compare it with get_pricing.

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

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

Names a specific resource (an agent doc) and its return form (markdown), and enumerates the four retrievable docs. It does not name a verb or explicitly position itself against the overlapping sibling get_pricing, so it stops short of full sibling 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?

There is no when-to-use or when-not-to-use guidance. With siblings like get_pricing and search_docs that plausibly overlap with the 'pricing' and doc-lookup cases, the description leaves the agent to infer which tool to pick.

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, so safety and repeat-safety are fully covered structurally. The description adds the useful nuance that pack prices are fixed while model prices vary, but says nothing about return shape or currency/regional behavior — acceptable given annotation coverage, but not 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 enumeration comes first and the sibling hand-off is last, which is the correct front-loading for a routing decision.

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?

No output schema exists, so the description carries the return-value burden — and it does name the four content categories an agent will get back. It stops short of describing structure or freshness of pricing data, which for a static info tool is a minor gap rather than a blocking one.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter text is needed and none is misleadingly implied.

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 enumerates exactly what the tool surfaces — credit packs with fixed prices, sign-up credits, payment methods, and the definition of a credit — which is effectively a specific resource statement for a no-argument info tool. It also separates itself from the sibling that covers per-model pricing, so an agent can tell the two apart without opening a schema.

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

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

'For per-model prices use list_models' gives an explicit alternative and the condition that selects it, which is strong routing. What's missing is any statement of when this tool itself is the right call (e.g., before purchase, when quoting costs), but the boundary case is covered.

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, closed-world, so the safety profile is covered. The description adds value beyond them by disclosing the response payload (model, prompt, settings) and its downstream use. Minor gap: no mention of not-found/error behavior or what 'public' excludes.

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

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

One tight sentence that front-loads the resource and scope, then the payload, then the follow-on actions. 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?

No output schema exists, but the description compensates by naming the returned payload and a follow-on action, which is enough for a trivial one-param lookup. Only minor omissions (failure modes, whether the template is copied or referenced) keep it off a 5.

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, including that an id may be used. The description's 'by slug or id' restates the schema rather than adding format or validation detail, so 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 (fetch one public template) and scopes it to a single item by slug or id, which implicitly separates it from list_templates. It also names the returned payload contents (model, prompt, settings), so the agent knows what it gets.

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

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

Gives concrete next-step context: use it to feed the product server's generate tools or open the url in Splice. It doesn't explicitly contrast with list_templates (bulk listing) or get_doc, but the context for when this is the right call is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond them: it discloses the return shape (price units — fixed, per second, or token; variants for options like resolution), the presence of routing tags, and a prerequisite workflow (consult get_model_guide first). No pagination, ordering, or result-count behavior is mentioned.

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

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

One dense sentence front-loads the resource and payload, followed by a short help pointer. Parenthetical clauses make it heavy to parse, but every element (price units, variants, tags, guide prerequisite) carries information an agent needs.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating price semantics, variants, is_default, routing tags, and guide. Minor gaps remain around result ordering and whether all models or only enabled ones are paginated, but nothing critical is missing for a read-only one-parameter list call.

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 'type' parameter is fully documented with a pattern and example values, so the description adds nothing beyond 'one generator type'. Baseline 3 is appropriate; the description correctly signals single-type scoping but supplies no additional syntax or constraints.

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

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

The description names a specific resource (enabled models for one generator type) and enumerates the payload fields returned (price in credits, is_default, routing tags, guide), which lets an agent distinguish it from get_pricing and list_templates. It never states an explicit verb or contrasts itself against those siblings, so it falls 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 only procedural guidance is downstream ('read get_model_guide before prompting a model the first time') plus a pointer to get_tool_help, which tells the agent what to do after calling, not when to call this instead of get_pricing. Usage is implied by the 'enabled models for one generator type' scope, but no exclusions or alternatives are given.

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 disclose readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful behavioral context by saying it returns summaries rather than full payloads, but it does not describe pagination, result ordering, or any rate/auth constraints.

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

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

Two concise sentences, front-loaded with the core purpose and followed by the key differentiation from get_template. Every clause contributes useful 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?

For a read-only list tool with annotations and no output schema, the description is nearly sufficient: it explains that results are summaries and points to get_template for full payloads. It could be slightly more complete by mentioning pagination or the summary fields, but the core invocation guidance is present.

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%, with limit, query, and offset documented in the schema. The description mentions media categories generally but does not explain the category parameter or clarify that media_kind supports voice as well as image, video, music, and motion, so it adds only limited meaning beyond the schema.

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

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

The description states a specific action and resource: browsing the public template library, with examples of what a template contains (model + prompt + settings recipes). It explicitly distinguishes itself from get_template, so an agent can tell the two apart without inspecting schemas.

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

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

It clearly positions this tool as the browsing/list-summary option and names get_template as the alternative for retrieving one template with its ready-to-run payload. It does not give explicit when-not guidance or mention search/filter behavior beyond the schema, so it is strong but not complete.

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 and closed-world, so the safety profile is covered. The description adds meaningful context beyond that: this is keyword (not semantic) matching and it returns best-matching sections with their text, which tells the agent what kind of results to expect.

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 with zero waste: what it searches, what it returns, and the alternative. The scope statement 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 two-parameter search tool with full annotation coverage, this covers purpose, scope, return shape and the sibling alternative. No output schema exists, but the description states the response form ('best-matching sections with their text'), so nothing essential is missing.

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

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

Schema description coverage is 100%, so both 'query' and 'limit' (with examples and default) are already documented in the schema. The description adds nothing about parameter behavior, so the baseline of 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 and resource ('Keyword search over the Splice agent docs') and enumerates the covered topics, then contrasts with the sibling that returns whole documents. 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?

'Use get_doc for a whole document' gives an explicit alternative and the condition that selects it. It does not address when to prefer get_pricing or list_* siblings, so the routing picture is clear but not exhaustive.

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