Renderball

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

Annotations only declare write/non-destructive/open-world. The description adds substantive behavior beyond that: the call returns page 1's brief, the flow is iterative with each reply carrying the next page's brief, and brand colours must be sourced from the real site rather than guessed. Auth/rate details are absent but the workflow contract is well 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?

Purpose is front-loaded, followed by brand guidance and then the post-creation workflow. It is dense but each sentence carries actionable instruction; the brand-colour digression is the only slightly padded element.

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 6-parameter, nested-object, no-output-schema tool, the description covers what the call produces (the next page's brief) and how to continue with submit_page, which is the critical missing piece from structured fields. Return-shape detail and the outline-vs-pages distinction remain unstated.

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 the schema already carries parameter meaning. The description restates the brand-colour rule (lead colour = buttons/large areas, not link colour) and the website requirement, which largely duplicates the accent and website schema descriptions rather than adding new semantics.

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

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

The opening sentence gives a specific verb and resource ('Start a new presentation') and names its three inputs (brief, brand, outline). It does not explicitly differentiate itself from siblings like write_outline or submit_deck, though the mention of submit_page hints at the workflow.

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 operational context: read the brand's site for real colours first, always supply the website, never invent a colour, and after creation the reply carries page 1's brief which you write and send via submit_page. It stops short of stating when to choose create_deck over alternatives such as write_outline or the outline-vs-pages trade-off.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds meaningful behavioral context: the three terminal/transient states and what each carries (editor link, rendered pages for review, failure reason). It does not mention auth requirements or polling behavior, but the state enumeration is genuinely informative.

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 front-loaded sentence that leads with the question it answers ('whether a submitted deck is...'), with the outcome list parenthetically scoped. No wasted words; only the nested parenthetical slightly burdens readability.

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

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

With no output schema, the description must carry return-value burden, and it does by enumerating the possible states and payloads. The only gap is that deck_id's provenance and format are never explained, which matters 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?

Only one parameter, deck_id, and schema description coverage is 0%. The description implies the id refers to a submitted deck, adding a little semantic framing, but says nothing about the identifier's format or origin (e.g., returned by submit_deck). Baseline for a small schema is 3.

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

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

The description states exactly what the tool returns: the import state of a submitted deck, enumerated as importing, ready, or failed. It is distinguishable from siblings like see_deck or submit_deck, though it never names the retrieval verb or explicitly contrasts with 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?

Usage is only implied via 'a submitted deck' – the agent can infer this is called after submit_deck, but there is no explicit when-to-use statement and no named alternative. Adequate but leaves the agent to infer the lifecycle position.

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 declare the tool is a non-read-only, destructive write. The description adds substantial context beyond that: atomicity ('Applied in order, all or nothing'), the refusal behavior ('A refused edit changes nothing and says why'), that untouched content including the user's own edits is preserved, and that the change is immediately visible and undoable. That is a rich behavioral profile for a mutation 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?

Front-loaded with the core mechanism (find/replace exactly-once semantics) before the routing advice, and every clause carries information. It is a dense, long paragraph with several stacked ideas, which slightly hurts scannability, but nothing is 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 six-parameter mutation tool with no output schema, the description covers what an agent needs: the edit mechanism, atomic failure semantics, page/shared selection, the undo guarantee, and even the return ('The reply shows the page as it looks now'). Nothing material is left unstated.

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 already 83%, so the schema carries most parameter documentation. The description still adds meaning the schema does not: the relationship between page and shared ('One page per call, or shared: true for the code every page shares') and the guarantee that untouched content survives. It does not add anything for deck_id or the find/replace length limits, but the schema covers those.

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 ('Change part of a design that already exists') and pins down the mechanism precisely: surgical find/replace against text from read_page, one page per call. This clearly separates it from siblings like read_page, create_deck, and write_outline, which either read or author whole pages.

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 an explicit when ('any change the person asks for in an existing design — a headline, a colour, a picture, moving or removing something') and an explicit alternative to avoid ('instead of sending the whole page again'). It also scopes the shared:true branch ('Only when the person asks to change the whole design') and states the refusal condition, leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful precondition that an outline must already be saved, but does not describe return format, auth, or rate limits.

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 concise sentence with no filler. It is not front-loaded with a verb, but it wastes no words and communicates the core resource and precondition immediately.

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 retrieval tool with annotations covering safety, the description gives the purpose and a key precondition. It remains incomplete on parameter meaning and sibling routing (e.g., get_page_brief), which an agent would need for confident selection.

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

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

With one required parameter and 0% schema description coverage, the description must carry the explanation. It only implies 'deck' maps to deck_id and gives no semantics, format, or constraint details (e.g., min/max length).

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 the resource ('writing brief') and scopes it to a deck rather than a page, which helps distinguish it from get_page_brief. However, it is a noun phrase without an explicit verb and does not name the sibling it contrasts with.

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 states a precondition ('whose outline is already saved'), which implies the tool is used after outline creation. But it does not say when to use this instead of alternatives like get_page_brief or write_outline, nor any exclusions.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the useful constraint that at most 4 pages are returned and where the ids come from, but says nothing about the shape or size of what comes back.

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 sentence with no filler; the cardinality limit and the routing condition are front-loaded and both earn their place.

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

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

With no output schema, the description carries the burden of explaining what a returned example page contains, and it only implies this. Combined with the undocumented deck_id, the definition is usable but leaves real gaps for a read tool whose return value is the whole point.

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 50%: 'ids' is documented in the schema with format and an example, while 'deck_id' has no description anywhere. The description supplements the ids parameter by tying it to the page brief's list, which is genuine added meaning, but the undocumented deck_id keeps this at a baseline 3.

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 (read) and resource (the studio's example pages) and states the cardinality cap ('up to 4'), which cleanly separates it from siblings like read_page and get_page_brief. It stops short of explicitly naming an alternative tool, but an agent can tell what this does without opening the 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?

'Read the ones that fit the page you are about to write' gives a clear situational trigger, and the reference to ids 'listed in a page brief' implies the get_page_brief → get_examples workflow. There is no explicit when-not guidance or named sibling to avoid, so it falls 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 description adds real context beyond the annotations: the brief already arrives via create_deck and submit_page replies, and non-page-1 briefs depend on page 1 being saved. However, readOnlyHint=false is unexplained — for a tool whose name and text imply a pure fetch, the agent gets no hint of what non-read-only behavior occurs. Some value added, one notable 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?

Three dense sentences, front-loaded with the payload contents before the usage advice; no filler. Slight deduction because the 'You rarely need it' caveat arrives mid-paragraph and reads a little sideways for an agent scanning for the trigger condition.

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 usefully enumerates what comes back (method, rules, per-page examples, page 1's file for continuation) and the ordering prerequisite. Remaining gaps are deck_id semantics and the unexplained readOnlyHint=false, but overall 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 50%: 'page' is documented inline (1-based, page 1 must be saved first), 'deck_id' is not documented in either place. The description reinforces page ordering ('after page 1, page 1's file to continue') but adds nothing about deck_id's format or provenance, so it only marginally compensates.

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 'the full writing brief for ONE page') and then enumerates the payload: the studio's method, the rules, the examples chosen for that page, and page 1's file. The word 'ONE' and the explicit contrast with 'page 1's brief comes with create_deck' carves out scope against siblings like get_brief and get_examples.

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 covers when NOT to use it ('You rarely need it: page 1's brief comes with create_deck and each submit_page reply carries the next page's') and then names the one condition that selects it ('a helper that writes one page with nothing in front of it'). That is a full use/don't-use/alternative picture.

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 this a safe, non-destructive, non-open-world read. The description adds genuinely new behavioral context: authentication is required, results are ordered newest first, entries carry editor links, and the currently open design is surfaced first and flagged open_now. It omits pagination or result-size limits.

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 returned before the auth and ordering details, with no padding. The final clause about the editor's open design is slightly convoluted but earns its place by naming the open_now marker.

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 must carry the return-value burden, and it does: ordering, editor links, and the open_now field are all disclosed. Only pagination/limits and sibling differentiation are missing, which are minor for a zero-parameter 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 takes zero parameters, so the baseline is 4 per the rubric. There is nothing further for the description to clarify about inputs.

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 resource (the user's Renderball documents) and its key attributes: newest-first ordering, editor links, and an open_now marker. It never names a sibling like see_deck or deck_status, so the agent must infer the distinction from the name alone, but the returned resource is unambiguous.

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

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

It states a prerequisite ('Needs an account (a key)') and implicitly scopes results to the authenticated user, which is useful. However, it gives no guidance on when to prefer this over see_deck or deck_status, 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 establish the safe-read profile (readOnly, non-destructive, closed-world), and the description adds substantive behavior beyond that: it enumerates the reply contents (page code, shared code, element ids, the currently selected element). This tells the agent exactly what it will receive, which annotations cannot.

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?

Front-loaded with the core action and the freshness constraint before the when-to-use clause and the return-value detail. Slightly long with three stacked clauses, but each carries information rather than 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?

There is no output schema, so the description must cover return values, and it does so fully (page code, shared code, element ids, selected element). Combined with the annotations' safety profile, an agent has everything needed to call this correctly and interpret the result.

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 67%, with page and with_shared documented in the schema and deck_id undocumented. The description doesn't add format or semantics for any parameter, though its mention of 'the code every page shares' loosely contextualizes with_shared. Baseline 3 is appropriate where the schema does most of the work.

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 (read) and resource (one page of a design) and qualifies the scope sharply: 'as it is NOW — the code the person's editor shows, including their own edits.' This freshness framing implicitly separates it from a brief-style sibling like get_page_brief, but no sibling is named, 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?

'Use it whenever the person asks to change something in a design that already exists' gives an explicit trigger condition and the rationale ('their editor may hold edits you have not seen'). It stops short of naming when-not-to-use or naming the alternative (get_page_brief / edit_page) directly, so it is clear context without exclusions.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the return type (images), the page ordering, and the hard precondition that the deck must already be rendered.

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 sentence with an em-dash aside that front-loads what is returned before the inspection checklist and remediation step. Slightly run-on, but every clause carries actionable 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 say what comes back (rendered page images, page 1 first) and under what condition it is available, which is what an agent needs to call it correctly. Details like image count or resolution are absent but not critical.

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?

There is one parameter (deck_id) with 0% schema description coverage, so the schema contributes almost nothing. The description implies a rendered deck is required but never explains the identifier's format or constraints, leaving most parameter meaning to 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 description states the resource ('the deck's rendered pages as images') and ordering (page 1 first), which lets an agent distinguish this visual-inspection tool from read_page. It is phrased as a noun fragment rather than a verb+resource, so it stops just 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?

It gives explicit when-to-use context (inspect for overlapping/clipped text, odd spacing, misplaced elements, mismatched pictures) and the follow-up action (fix that page and submit_page it again), naming the sibling tool to route to. The precondition for availability is stated as well.

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 flag readOnlyHint=false, destructiveHint=true and openWorldHint=true; the description adds that the result is a publicly accessible link viewable by anyone, which clarifies the exposure risk behind the destructive flag. It does not say whether sharing can be revoked, whether permissions are required, or whether repeat calls are idempotent.

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 front-loaded sentence with a colon clause that states the mechanism and its consequence. No filler, no repetition of the title.

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

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

For a one-parameter, no-output-schema tool the description is nearly sufficient: it says what is toggled and that the link is returned. What remains unaddressed is reversibility (can the link be turned off) and the permission requirements implied by destructiveHint=true.

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?

Only one parameter, deck_id, and schema description coverage is 0%, so the description carries some burden. However the parameter name is self-explanatory and the schema already documents the string type and length bounds; the description adds no format or sourcing detail (e.g., where to obtain the id).

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?

"Turn on the public link for a deck and return it" gives a specific verb (enable public sharing) and resource (deck), and the effect clause distinguishes it from read-only siblings like see_deck or list_decks. It stops short of explicitly naming a sibling or exclusion, so it lands just below the top band.

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 statement of when to use this versus alternatives such as see_deck or submit_deck, nor any prerequisite or exclusion. The public-link consequence implies a use case, but the agent is left to infer it.

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 flag destructiveHint/readOnlyHint; the description goes further by explaining exactly what is destroyed (the whole file is replaced), the refusal condition, the server-side validation and rendering behavior ('checks it against the brief, renders every page'), and the two concrete return states with the editor_url and the polling fallback. That is real behavioral context beyond the structured hints.

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

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

Dense but front-loaded: the primary action comes first, then the sibling-routing caveat, then the outcome. The mid-sentence parenthetical interrupts flow slightly, but every sentence carries information the 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 completely: 'ready' plus editor_url, or 'importing' plus the instruction to poll deck_status. Combined with the destructive scope, refusal condition, and usage split against submit_page, 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 coverage is 75% and 'source' is well documented in the schema itself. The description adds the conceptual framing that source is the complete deck file rather than a page, and indirectly explains wait_seconds ('or importing — then poll deck_status'), but says nothing about label. Baseline 3 is appropriate when the schema carries most of the load.

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 (replace/submit) and resource (the whole deck file) and explicitly scopes it to decks 'whose pages are all written,' which cleanly separates it from submit_page. An agent can pick between the two siblings 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?

Gives an explicit alternative and the condition that selects it: 'while pages are still being written, submit_page each one — a whole file is refused then.' It also routes the follow-up case ('importing' → poll deck_status), so both the when and the what-next are 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 readOnlyHint=false and destructiveHint=true, so the description doesn't need to re-warn about writes. It adds real behavior beyond that: what the reply carries (next page's brief, then merged/checked/rendered pages when the deck completes), and that a single-page resubmit replaces only that page while preserving the person's own edits. It does not spell out what a rejected submission returns, which is the main remaining 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?

Front-loaded with the core action and mode split, and most sentences do work (prerequisite, reply contents, rewrite semantics, alternatives). The rewrite clause is slightly padded ("everything else stays as it is, the person's own edits included"), but the length is justified by the tool's multi-mode workflow.

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

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

For an 8-parameter, no-output-schema workflow tool, the description covers the key state machine: prerequisite brief, what the reply returns at each stage, rewrite-vs-full-submit behavior, and when lighter siblings apply. It leaves open the failure/refusal path and how wait_seconds interacts with deck completion, but the operational essentials are 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 75%, so the schema already documents most parameters (source, direction, page_id, next_brief, wait_seconds, label). The description reinforces the page-1 vs page-N meaning of source and the one-sentence form of direction, but adds little syntax or format detail the schema lacks. 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?

States a specific verb and resource ("Save one page you wrote") and immediately disambiguates the two modes of the tool (page 1 carries Section0/shared design, page N carries only its Section). It also names the sibling tools that are not this one, so an agent can place it without opening any 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 routes the agent: use this tool to submit a page, submit just that page to rewrite one page of a finished design, and use read_page/edit_page when only part of a page changes. It also states a hard prerequisite ("A page is accepted only after its brief was handed to you") that gates invocation.

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 destructiveHint=true and readOnlyHint=false, so the description earns credit for specifying WHAT is destroyed: 'pages written for the old one are dropped.' It also discloses the unusual reply contract, that the reply carries page 1's brief. It does not mention authorization or irreversibility beyond the drop, but the key destructive behavior is named.

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

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

Two sentences, front-loaded with the action and the destructive consequence, then the reply behavior. It is appropriately sized, though the second sentence is slightly cryptic without knowing submit_page.

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 destructive write tool with no output schema and only 33% schema coverage, the description covers the destructive behavior and a key reply detail, but it leaves deck_id and tone unexplained and does not describe the full page object requirements. It is adequate but with clear 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 coverage is 33%, so the description must compensate, but it says nothing about deck_id, tone, or the shape of pages. The schema describes many nested fields, but neither the description nor the schema explains the top-level page array semantics. The reply contract is the only parameter-related value added.

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 ('Save a new page-by-page outline for a deck'), and names the consequence for existing pages. It is distinguishable from siblings like submit_page and edit_page.

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 the tool is used (creating a new outline) and that pages from the old outline are dropped, but it does not explicitly contrast with alternatives such as edit_page or submit_page, nor does it state whether it requires a prior create_deck.

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