EaseWeb

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

Annotations already declare this as a non-read-only, non-destructive, non-idempotent write. The description adds genuinely beyond that by disclosing the visibility model: the owner sees slide/presentation notes in the viewer, while a thread is visible to the owner and the thread starter. It does not cover retry/duplication behavior 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?

Two sentences, action-first, with the optional-parameter variants enumerated inline. The parenthetical quoted parameter names are a bit clunky and the second sentence is long, but nothing is redundant 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?

With an output schema present, return values need not be explained, and 100% schema coverage handles parameter documentation. For a four-parameter write tool this is nearly complete; the remaining gap is the interaction between reply_to and slide_id and any permission failure behavior.

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 baseline is 3. The description re-frames slide_id versus reply_to in terms of target (slide note vs whole-presentation note vs thread answer), which adds some meaning, but it never resolves the important semantic ambiguity of whether reply_to and slide_id can or must be combined.

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 gives a concrete verb+resource: leaving a note on a presentation/slide or replying to a thread, which is distinguishable from the sibling set (list_comments, delete_comment, resolve_comment). The only drag is terminology drift — it says "note" while the tool name and all siblings say "comment" — and it never explicitly names or excludes those siblings.

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

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

It does outline the three usage modes (slide-level, presentation-level, thread reply) and the access precondition ("any presentation you can see"), which is useful context. But it stops short of stating when to reply instead of starting a new note, whether the modes are mutually exclusive, or any alternative tool to use instead.

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, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is carried. The description adds the edit-permission prerequisite and notes that block props fall back to theme defaults indirectly, but its return-value sentence largely restates the 'response' parameter rather than disclosing new behavior beyond the structured fields.

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, front-loaded with the core action and placement behavior, with no filler. The inline quoted parameter names ('position', 'response') are the only mild density cost, so it stops short of a 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 13-param mutation tool with nested block objects, the description covers the essentials an agent needs: placement semantics, optional inline block creation, permission requirement, and response verbosity. With a full schema and an output schema present, the remaining gaps (block-prop details, clamping rules) are acceptable.

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 every parameter is already documented in the schema; the description only echoes 'position (1-based)' and the optional-blocks behavior without adding syntax or constraints the schema lacks. Baseline 3 is appropriate 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?

States a clear verb+resource ('Add a slide to a presentation') and adds scope qualifiers: edit permission, placement at end or at a 1-based position, and optional inline blocks. It is distinguishable from add_slides and edit_slides by implication ('a slide' vs bulk edit), but it never names the sibling that handles the batch case.

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 implied through the placement and inline-blocks options, and the 'presentation you may edit' phrasing hints at a permission prerequisite. It offers no explicit when-to-use or when-not-to-use guidance against add_slides (bulk add) or edit_slides (modify existing), which are the natural alternatives an agent must choose between.

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 the safety profile (non-readOnly, non-destructive, non-idempotent), so the bar is lower. The description still adds real behavioral context: the return shape (new slide ids, or full props when "response" is "full") and the non-obvious fact that slide links are resolved against post-insertion numbering. It does not state failure modes or what happens on partial insertion.

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 verb and scope, and every sentence carries information. The inline JSON-ish snippets mirror the schema and make it slightly harder to read than plain prose, but nothing is wasted.

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 4-parameter mutation tool with an output schema, the description covers insertion position, the response verbosity modes, and cross-slide link resolution. Return values largely live in the output schema, so it is close to complete; only error/edge-case behavior is unaddressed.

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 description goes beyond the schema by explaining the self-referential link semantics ({"kind": "slide", "slide_number": N} counts slides as they are after insertion), which is the one parameter behavior the schema does not convey. It also restates the slide object's field list, which is redundant with 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?

States a specific verb+resource ("Add several slides at once to a presentation") and names the scope of the operation (at end or from "position"). It implicitly differentiates from the sibling add_slide via "several slides at once", but never names the single-slide alternative, so an agent must infer the routing.

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 implied by the batch framing rather than stated: an agent can infer this is for multiple slides, but there is no explicit when-to-use/when-not or named alternative versus add_slide/edit_slides. The phrase "a presentation you may edit" does at least signal a permission prerequisite.

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, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds useful effect semantics (role alters what is granted; whole_project extends the grant), but says nothing about permissions required, notifications, or reversibility.

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 front-loaded sentences: the core action first, then parameter clarifications. Efficient, though the parenthetical definitions are slightly redundant with schema text.

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

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

With an output schema present, return values need no explanation, and all parameters are covered by the schema. The only gap is that the description does not point to list_access_requests for obtaining a request_id, which an agent must supply.

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 all four parameters are already documented, including the role enum and the whole_project default. The description restates role and whole_project semantics rather than adding format or edge-case 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?

The description states a specific action (approve or decline) on a specific resource (a request for access to your presentations or projects). An agent can distinguish this from siblings like set_access, request_access, and list_access_requests 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?

Usage is implied by the name and the mutation semantics, but the description never says when to use this versus alternatives such as set_access (direct access changes) or list_access_requests (finding a request_id). No prerequisites or workflow context 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 declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description goes well beyond that: it explains the server-side browser measurement versus font-width estimation ('measured': true), the visible-content-only rule where text on a block without fill/border can spill into padding, and the cross-tool behavior that mutating operations return layout_warnings. That is meaningful behavioral context; only the exact response shape is left unstated.

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 purpose is front-loaded, but the body is a single dense paragraph with stacked parentheticals and long clauses ('The changing operations add the (estimated) warnings of the slides they changed to their answer'), which makes it harder to scan. Every element is informative, but the structure could be tightened into discrete points.

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?

An output schema exists, so return values need not be described, and the description fills in the diagnostic semantics (warning categories, measurement method, visibility caveat) an agent needs to interpret results. The main remaining gap is guidance on when to invoke it versus preview/get siblings, which is a usage rather than completeness issue.

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 slug, slide_ids, from_number and to_number are already documented in the schema. The description adds nothing about the selector parameters, which is acceptable given full coverage, 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?

The description states a specific verb-ish purpose (reporting warnings about how slides look) and enumerates the exact conditions it detects: overflow, cut/outside, overlap, with the quoted keywords an agent would see in output. It clearly separates this analysis tool from mutation siblings. It stops short of naming a sibling such as preview_slides or get_slides to route the agent, so it is clear but not fully differentiated.

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?

Implicit usage is conveyed: check layout to learn about text/code that overflows, is clipped, or overlaps. It also hints that changing operations already append layout_warnings, which tells the agent it may not need a separate call. However, there is no explicit when-to-use / when-not-to-use statement or named alternative, leaving the routing 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 declare a non-destructive, non-idempotent, closed-world write. The description goes well beyond that by disclosing return behavior (new presentation with slide/block ids, full props with 'response': 'full'), the eager multi-language sync model, and that the answer reports 'missing_translations'. It lacks permission/auth context, hence not a 5.

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 purpose, then structured detail on the slides list, multilingual requirement, and return format. Information-dense with little waste, though several sentences are run-ons that slow parsing.

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 10-parameter tool with nested objects and an output schema, the description covers the essential mental model: structure of slides/blocks, the multilingual obligation, and what the response contains. It is complete enough to call correctly, though explicit 'when to prefer over add_slide' routing is absent.

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

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

Schema coverage is 100%, so the per-parameter baseline is 3, but the description adds cross-parameter semantics the schema does not: how slide objects link via {"kind": "slide", "slide_number": N}, and how lang, title_tr, name_tr, and per-block 'tr' must all be supplied together. This relational guidance is genuinely value-adding.

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 ('Create a new presentation') and clarifies the scope with 'empty or complete in one call', which distinguishes it from the incremental siblings add_slide/add_slides and from update_presentation. An agent can identify the creation path 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?

The phrase 'empty or complete in one call' implies this tool subsumes slide creation, but it never explicitly states when to use it versus add_slide, add_slides, or import_presentation. Usage is implied rather than spelled out, and no exclusions or prerequisites 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 declare a non-readonly, non-destructive, non-idempotent write, but they cannot express the side effect the description supplies: a presentation already in another project is moved out of it. That cross-resource mutation is exactly the kind of context annotations miss, though permissions/limits are not 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?

Two sentences, zero filler, and the primary action is front-loaded before the optional-parameter and side-effect details. Every clause carries information the caller 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description covers the notable side effect; only ownership/permission requirements for creating in a workspace are 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 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the presentations array is consumed 'in this order', and the one-project-per-presentation constraint governs which slugs are valid 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?

States a specific verb+resource ('Create a project') plus scope ('of yours') and the optional inclusion of presentations. It distinguishes itself from update_project/get_project only implicitly via the create framing and the move-over behavior; no sibling is named outright.

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 create framing implies when to use it versus update_project, but there is no explicit when-to-use, when-not-to-use, or alternative routing. The move-over sentence is behavioral, not usage guidance, so the agent must infer the boundary.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds two pieces of context the annotations cannot: the cascading deletion of replies when the note starts a thread, and the authorization requirement (author or presentation owner).

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, no filler, with the core action and its cascade effect front-loaded before the permission clause. Every clause 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?

With annotations covering the mutation/destructive profile, an output schema present, and the parameter fully documented, the description supplies the remaining critical facts: cascade deletion and who is authorized. Only the distinction from resolve_comment is left implicit.

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% for the single comment_id parameter, so the schema fully documents the input. The description adds no format, syntax, or lookup guidance beyond what the schema provides, making the baseline 3 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 ('Delete a note') and clarifies the cascade scope ('with its replies, when it starts a thread'). It is clearly distinguishable from add_comment/list_comments, though it does not explicitly contrast with resolve_comment, which is the nearest ambiguous 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?

Provides a permission condition ('Its author or the owner of the presentation may do it') but gives no explicit when-to-use guidance versus alternatives such as resolve_comment (which likely closes rather than removes a comment). 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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds the specific effect that the presentation disappears from the site and from the list, which is modest context beyond the annotations but no irreversibility or permission detail.

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 efficient sentence with the core action front-loaded and the parenthetical clarifying scope. No wasted verbiage, though the parenthetical is nearly redundant with the destructive annotation.

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?

An output schema exists, so return values need not be described, and annotations cover the destructive/idempotent nature. However, for a permanent deletion tool there is no word on reversibility or preconditions, leaving a small but real 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 100% with a single well-documented slug parameter, so the schema carries the semantic load. The description adds nothing about the identifier beyond what the schema already provides, matching the baseline for full 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?

States a specific verb (delete) and resource (presentation), making it immediately distinguishable from delete_slide and delete_project by name. It stops short of explicitly contrasting itself with siblings, but the action and target are 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?

There is no guidance on when to use this versus alternatives (e.g., restoring via restore_version, or deleting slides individually), nor any stated prerequisite such as required permissions or confirmation. The agent must infer usage entirely.

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, idempotentHint=true, readOnlyHint=false. The description adds genuinely new behavioral context: presentations are preserved, and their internal links dangle afterwards. That surviving-side-effect detail is exactly what annotations cannot express.

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, front-loaded with the action and followed by the exact consequence. No filler, no restatement 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?

An output schema exists and annotations carry the safety profile, so the description's job is narrow: clarify collateral effects. It does that well. What is missing is any mention of required permissions or whether the deletion is recoverable.

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 'project' param is documented as a slug with its address format. The description's 'of yours' hints at an ownership precondition but adds no syntax or identification detail beyond the schema. 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?

Clear specific verb+resource ('Delete a project'), scoped by ownership ('of yours'). The consequence sentence implicitly distinguishes it from delete_presentation (presentations survive), though no sibling is named explicitly.

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 statement of when to choose this over delete_presentation or update_project, and no prerequisites or warnings. Ownership ('of yours') is the only implied constraint; the rest is left 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds one genuinely useful side-effect disclosure — 'Links that led to it stop leading anywhere' — which is not derivable from annotations, but it says nothing about reversibility (restore_version exists) or the conflict behavior beyond what the schema already documents.

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, zero filler, with the action stated first and the consequence second. Every clause 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?

An output schema exists, annotations cover the safety profile, and all three parameters are documented in the schema, so the description need not restate returns or field meanings. What is missing is guidance on when deletion is appropriate versus editing or restoring, and any note on whether the deletion is recoverable.

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%, with slug, slide_id, and the optional base_version all fully explained in the schema itself, including the 409 conflict semantics. The description adds no parameter-level detail, 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 (Delete) and resource (a slide of your presentation), which cleanly separates it from delete_presentation, delete_comment, and delete_project by resource type. It never explicitly contrasts with the neighboring slide-mutating tools (add_slide, update_slide, edit_slides), 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, no prerequisites, and no mention of alternatives such as update_slide or restore_version. The agent must infer usage entirely from the tool name and the sibling list.

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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses meaningful behavior: update only alters the given props, props a block type lacks are skipped, added blocks land on top unless at_bottom is set, and response defaults to brief. It stops short of covering permissions/auth or the semantics of the destructive 'delete' path.

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-loads the core idea in the first clause, then breaks add/update/delete into compact labeled segments. Dense and example-driven but every sentence carries operational detail; 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 an 8-parameter tool with multi-shape params, the description covers the operation semantics and default behaviors well, and the output schema (present) handles return values. The main residual gap is the absence of routing guidance versus sibling edit/slide-mutation tools.

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 100% (baseline 3), and the description adds real meaning on top: it details the three update shapes (single id, ids list, and the 'inside' card form) and explains that 'inside' covers the card background block plus every block within its rectangle. That 'inside' semantics is not conveyed by the schema description alone.

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

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

The description states a specific verb+resource scope: 'Change some blocks of a slide and leave the others alone, in one step', and enumerates the three operations (add/update/delete) it supports. The 'blocks' focus clearly distinguishes it from siblings like edit_slides, update_slide, and replace_text without needing to open 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?

It implies when to use it ('leave the others alone, in one step' = a surgical partial edit) but never names an alternative tool or states a when-not condition. With siblings edit_slides, update_slide, and replace_text all in play, the agent must infer which 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?

Goes well beyond the annotations by disclosing atomicity ('Nothing is changed when one item is wrong'), optimistic-concurrency behavior ('or its slide changed meanwhile'), and the version-history effect. These are non-obvious traits not derivable from readOnlyHint/destructiveHint, and they do not conflict with destructiveHint=false since deletes are recoverable through the created version.

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 one-step value proposition and otherwise dense with essential semantics; there is some packing of three operations into a single sentence, but no filler 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?

A high-complexity batch mutation tool whose gotchas (atomicity, concurrency check, history version, response verbosity) are all covered; return values are further backed by an output schema, so nothing critical 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?

The schema types `edits.items` only as a generic object, and the description compensates fully by spelling out the item keys (slide_id, add, update, delete, at_bottom, base_version) and the semantics of add placement, update targeting (id/ids/inside), and delete. Without it, the array would be opaque.

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+scope: 'Change blocks on many slides in one step (and one version in the history)'. The batch scope implicitly distinguishes it from edit_blocks/update_slide, but no sibling is named explicitly, so an agent must infer that edit_blocks is the single-slide variant.

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 'in one step' phrasing implies this is the batch alternative to single-slide editing and surfaces the versioning advantage, but there is no explicit when-to-use/when-not statement or named alternative among the many sibling write tools (edit_blocks, update_slide, add_slide, reorder_slides).

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 the description adds genuinely new behavior: the returned download URL works without a key for one hour (temporal/auth detail), export is restricted to the author (authorization), and each format's fidelity is described. This is meaningful added context beyond the structured fields.

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 single paragraph with zero filler; the format enumeration carries most of the information load and the permission constraint is placed last. The leading fragment 'A file of one of your presentations:' is slightly awkward as an opener but quickly resolves into specifics.

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?

Covers the essentials for a low-complexity, 2-param tool: output artifact types, the download URL, its expiry, and the caller restriction. With an output schema present there is no obligation to describe return structure, so the remaining gap (error modes) is minor.

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, but the description goes beyond the schema's terse 'The kind of file' by explaining what each enum value actually contains and whether it is editable or re-importable. That materially disambiguates the format choice.

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 verb+resource ('export' a 'presentation') and immediately distinguishes itself from siblings like import_presentation and get_format by enumerating the three output artifacts it produces. An agent can tell exactly what this tool produces 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?

Gives clear selection guidance for the format enum (pptx = editable, zip = site archive re-importable, pdf = viewer-faithful), which is effectively when-to-use guidance for the enum. It also states the authorization prerequisite ('Only the author may export'). It does not explicitly name an alternative sibling for related reads, so it falls just short of 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious domain behavior: effective_level inheritance where a presentation in a project inherits the project's level when that one is stricter. That inheritance rule is real value beyond annotations. However it doesn't clarify whether output is a snapshot, or that pending requests are included read-only (vs. the actionable list elsewhere).

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 that is really a field inventory, and it is not front-loaded with the action. It spends its length enumerating return-value fields (which an output schema already covers) rather than stating what the tool does or when to use it.

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?

An output schema exists, so return values needn't be explained in prose; the field enumeration is largely redundant with that schema. The inheritance rule is a useful addition, but the definition still lacks a plain purpose statement and any routing versus siblings, leaving the agent to infer when to call 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?

Schema coverage is 100% and the single 'slug' parameter is fully documented in the schema as the presentation's address. The description adds no parameter meaning beyond what the schema provides, which is the baseline-3 case.

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 the fields of the access settings object (own level, effective level, who has access, pending requests) but never states the action plainly: that it retrieves/returns the access settings for a presentation. There is no leading verb like 'Get' or 'Return'. The agent can infer it's a read from the name and annotations, but the sentence itself is a content list rather than a purpose 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?

No guidance on when to use this vs. siblings like list_access_requests, whoami, request_access, or set_access. An agent cannot tell from the description whether pending requests returned here overlap with list_access_requests, or that set_access is the mutation counterpart. Usage must be inferred entirely.

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 fully covered and the description does not contradict it. The description adds that this is a 'complete reference' (i.e. static documentation data), but offers no additional behavioral context beyond that; with annotations carrying the load, a 3 is appropriate.

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-separated inventory of what the reference contains; nothing is padded. The enumeration is long but each item earns its place by signalling the reference's breadth.

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 static reference with an output schema already describing the returned structure, the description is largely complete — the agent needs no return-value detail. The only gap is the absent routing guidance relative to the many block/slide-editing siblings.

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. There are no argument semantics to clarify, and the description correctly does not waste space inventing any.

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 and enumerates its contents precisely ('block types with every prop and its default, allowed values of every enumerated prop, number ranges, colour props...'), so an agent knows this returns a schema-style reference document rather than slide data. It does not, however, explicitly contrast itself with adjacent tools such as check_layout or get_slide, so the distinction is inferable rather than stated.

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 guidance: nothing says to consult this before add_slide/edit_blocks, nor how it relates to check_layout. The agent must infer that this is a lookup resource for block structure. No alternatives or exclusions are offered.

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 carry the read-only/idempotent safety profile, and the description adds genuinely useful behavior: the size warning (a 30-slide deck is a few hundred thousand characters), how to page with from_number/to_number or slide_ids, what texts_only returns, and that each slide's 'version' must be passed as base_version on edits. It stops short of describing return envelope or link-resolution structure in depth.

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?

It is front-loaded around the core return shape and then the paging advice, with zero filler sentences. The heavy parentheticals and quotation marks make it dense, but each sentence 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 an output schema present, the description needn't enumerate return values, and it still covers the practical concerns an agent faces: paging, size, texts_only, can_edit, and version/base_version coupling. It leaves the sibling-routing question open, which is the main missing piece.

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, and the description goes beyond the schema by explaining the intent behind texts_only ('only the words of the blocks (html, tr, code), no geometry') and the from/to_number paging pattern. It slightly blurs base_version (an output field consumed by edit tools) into this tool's surface, but the extra semantics are real.

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 gives a specific verb+resource and scope: it returns every slide and every block (ids and complete props) in playback order, and frames it as 'for editing'. It implies a distinction from single-slide readers like get_slide, but never names a sibling, so the differentiation is left to inference.

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 tells the agent to use the returned ids to edit slides and blocks and advises reading large presentations in parts, which implies the workflow. However it never states when to prefer this over get_slide, get_slides, or read_presentation, so the routing among closely-named siblings is unaddressed.

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, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds that only visible projects and presentations are returned and that presentations come in order, which is genuine extra context, but it says nothing about error/not-found behavior for a slug the caller cannot see.

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?

It is short, but the parenthetical '(the ones you can see)' interrupts an already fragmentary sentence and there is no front-loaded statement of what the tool does. Brevity here reads as under-specification rather than efficient 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?

With an output schema present, return values need not be explained, yet the description spends its only sentence on return composition. Annotations cover safety. For a low-complexity single-parameter read the description is minimally sufficient, but it never states the fundamental purpose or when to reach for 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 single 'project' parameter has 100% schema description coverage, including the slug format '/project/<slug>/'. The description adds no parameter-level meaning, so the schema-only 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?

The description is a noun phrase with no verb, so the action (fetch/retrieve one project) is only implied by the name 'get_project'. It does add return-content information ('with its presentations ... in order'), which goes slightly beyond a tautology, but it never distinguishes this tool from get_presentation or list_projects.

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 tool versus get_presentation, list_projects, or get_slide. The phrase 'the ones you can see' hints at a permission scope but is not framed as usage guidance, so an agent gets no routing help.

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 non-openWorld, so the safety profile is fully covered. The description adds modest value by explaining that the returned slide includes all blocks with ids and complete props, but says nothing about visibility/permission constraints or pagination that a 'can see' qualifier hints at.

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 efficiently conveys scope and return content with no filler. It is arguably terse, but every clause 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?

With an output schema covering return values and annotations covering safety, the description needn't explain those. For a simple two-param read tool it is close to complete, but given the crowded sibling set it should have clarified when to prefer this over get_presentation/read_presentation.

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%; both slug and slide_id are well documented (including the stable-id-vs-position caveat). The description adds nothing beyond the schema, so the 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?

Names a specific verb and resource (get one slide) plus what it returns ('all of its blocks (ids and complete props)'), so the agent knows exactly what it fetches. However, it does not distinguish itself from close siblings like get_presentation, read_presentation, or preview_slides, leaving the 'one slide vs whole deck' boundary implicit.

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 guidance, no prerequisites, and no mention of alternatives. The presence of get_presentation, read_presentation, update_slide, and preview_slides among siblings makes routing ambiguous, and the description offers nothing to resolve 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 already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the per-slide 'version' should be passed back as 'base_version' when changing a slide, and the response carries the presentation 'version' and 'slides_total' — meaningful for optimistic-concurrency editing.

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 what is returned, then parameter and version semantics. It is dense and reads as one long dash-separated sentence, but nearly every clause carries information an agent needs; little is wasted.

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

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

With an output schema present, the description needn't document return values, yet it usefully flags version and slides_total. All five parameters are covered and the editing/version workflow is explained, leaving only alternative-tool routing unaddressed.

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 description adds meaning the schema does not: from_number/to_number are 1-based and inclusive, and texts_only yields html/tr/code block text with 'no geometry', clarifying what is dropped. That is genuine added value over the schema text.

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 (get slides) plus scope: a subset of a larger presentation with blocks containing ids and complete props. The partial-retrieval framing implicitly contrasts with whole-presentation reads, but no sibling (get_slide, read_presentation, preview_slides) is named, so differentiation is left to inference.

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 does give a use-case cue for texts_only ('for reading, checking or translating') and explains the numbering/ids selection, which is useful. However there is no explicit when-to-use-vs-alternatives guidance — nothing tells the agent when to pick this over get_slide or read_presentation.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds some value by characterizing what is returned (slides and texts as markdown, or complete content as json), but says nothing about permissions actually required, size limits, or behavior on a non-existent version number.

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 compact sentence with the format options enumerated inline; nothing is wasted. The opening clause 'What a presentation you may edit looked like in a version' is slightly convoluted, which keeps it from a 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?

With an output schema present, return values needn't be explained, and the schema covers all three parameters. However, the description omits how an agent obtains a valid version number and how this read relates to restore_version, which is a noticeable gap for a tool living among many version/history siblings.

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 documents slug, number, and format, and the enum with its default. The description repeats the format semantics ('markdown' default, 'json' complete content) rather than adding syntax or constraints beyond the schema. Baseline 3 applies when the schema carries 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?

The description names a specific verb+resource combo — retrieving the content of a version of a presentation — and the format clause clarifies what 'content' means. It is clear on its own but does not distinguish itself from siblings like list_history, restore_version, or read_presentation, so the agent must still infer where it fits.

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 phrase 'a presentation you may edit' hints at a permission precondition but says nothing about when this tool should be chosen over list_history (finding the version number) or restore_version (reverting). No alternatives or exclusions are named.

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 cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description goes well beyond: it discloses the returned 'warnings', the brief/full response distinction, the slide-N replacement semantics that preserve id/links/notes/history, preservation of translations, title/theme/slide-name/script retention, and a 409 refusal on version conflict. This is unusually rich 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?

Two dense paragraphs, front-loaded with the create path before the 'into' update path, which is the right ordering. Almost every clause carries information; length is justified by 11 parameters and two distinct modes, though it could be tightened slightly.

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?

An output schema exists, so return values need not be explained, and the description still covers the key output cues (ids unless 'full', warnings). For an 11-parameter import tool with an update mode, it covers both modes, edge cases, and the version-conflict guard, leaving nothing an agent needs 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%, so the per-parameter baseline is 3. The description adds genuine cross-parameter meaning beyond the schema: how 'into' interacts with 'slides' (slide N replaces slide N, file slides after the last are added), what 'base_version' guards against (409), and what 'response' changes. It does not re-explain every field, but the interaction semantics are real added value.

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 (create a presentation) constrained to two file formats (.pptx, .zip as exported by the site), and enumerates what becomes editable (slides, texts, shapes, pictures, backgrounds, links). It is clearly distinguished from a blank-create sibling because it is scoped to file import, and it names the second mode ('into') without ambiguity.

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 explains the two usage modes: no 'into' creates a new presentation, and with 'into' the file updates an existing one. Context is strong, but no alternative sibling (e.g. create_presentation or upload_image) is named as a 'when not to use this' option, so the routing guidance stops short of explicit exclusivity.

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, non-destructive and closed-world, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond that: by default only pending requests are returned unless include_decided is set. It says nothing about ordering, limits, or pagination.

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, front-loaded sentences with no filler. Slightly awkward quoting and punctuation, but every clause carries information and nothing is padded.

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?

An output schema exists so return values need no explanation, and annotations carry the safety profile. However, for a list tool sitting among 40 siblings with closely related request/access tools, the description omits the basic purpose statement and any routing, leaving the definition only minimally 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 description coverage is 100%, and the description essentially paraphrases the schema text for both parameters ("incoming" default, include_decided behavior) rather than adding format or edge-case meaning. Baseline 3 is appropriate when the schema already does this 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?

The description never states that this tool lists access requests in a sentence of its own; it jumps straight into the meaning of the "direction" parameter values. The tool name carries the actual purpose, and the description only clarifies scope (incoming vs outgoing). It is decipherable but the verb+resource statement is implied rather than stated, and no sibling (e.g. get_access, request_access) is distinguished.

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 guidance and no mention of alternatives. An agent must infer from context whether to call this versus get_access, request_access, or answer_access_request. The "default" note for incoming is a small hint but not routing 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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond the annotations: per-user visibility scoping and the default that resolved threads are excluded unless include_resolved is 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?

Three short sentences with no filler and the core resource description front-loaded. The final sentence is telegraphic but still readable and earns its place by stating the default filter.

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

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

With an output schema present, return-value details need not be described, and the description covers scope, visibility, and default filtering adequately for a three-parameter read tool. Nothing essential to correct invocation appears 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 a baseline of 3 applies. The description goes slightly beyond the schema by clarifying the default filtering semantics of include_resolved ("Without include_resolved only open threads"), which reinforces the meaning of that parameter rather than merely restating it.

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?

Describes the resource as notes on a presentation returned as threads with replies, which is specific enough to distinguish it from siblings like add_comment, delete_comment, and resolve_comment. The verb is only implied by the title ("Read the notes") rather than stated in the description, but the resource scope 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?

Explains who sees what (owner sees every note, others see only their own threads) and the default filtering of resolved threads, which is useful context for deciding relevance. However, it never explicitly routes the agent away from alternatives such as get_slide or read_presentation, so usage is implied rather than stated.

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 readOnly, idempotent, non-destructive and closed-world behavior, so the bar is lower, and the description still adds real semantics beyond them: the newest-first ordering, the non-obvious aggregation rule (one author's consecutive changes within 10 minutes collapse to a single version), and the permission-based visibility rule. It omits pagination/limit behavior, but the added behavioral context is substantive.

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 carrying distinct information, front-loaded with the resource and its ordering. There is no filler; the only slight cost is that the opening sentence is dense with the returned-field list.

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?

An output schema exists, so return values need not be explained in prose, and the description still covers ordering, the version-grouping rule, and the visibility constraint. For a two-parameter read-only list tool this is nearly complete; only pagination behavior around limit 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 description coverage is 100%, with both slug and limit fully documented in the schema (including the default of 50). The description adds no extra meaning to either parameter, 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?

The description states a specific resource and its scope: versions of a presentation the caller may edit, returned newest first, with the fields it exposes (number, author, timestamp, diff). It is clear and distinguishable, but it never names or contrasts with the closely related siblings get_version and restore_version, so sibling differentiation is left to inference.

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 context is implied rather than stated: it tells you the history is only visible to those who can edit, which implicitly routes read-only users away. However, it gives no explicit guidance on when to call this versus get_version (single version) or restore_version (revert), so the agent must infer the boundary.

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, lowering the bar. The description adds useful access semantics beyond that – notably that 'open' presentations may be read and edited by any signed-in person or agent, and that each record exposes an editability flag and access level, which helps the agent reason about permissions.

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 scope definitions the agent needs first, then the field inventory. It is appropriately sized, though the field-list sentence reads as a run-on inventory rather than clearly separated clauses.

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

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

With an output schema present, the field enumeration is partly redundant, but the access-level/editability semantics and scope meanings round out the picture. Nothing critical for a filtered, read-only list call 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 parameters (scope, project) are fully documented in the schema, including the note that project overrides scope. The description largely restates the scope enum without adding syntax or precedence detail beyond what the schema already provides, 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 ('List presentations') and immediately defines the three scopes it can return, so an agent knows exactly what the tool yields. It doesn't explicitly contrast itself with get_presentation or the other list_* siblings, but the resource noun is distinctive enough to avoid confusion.

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 scope definitions tell the agent which filter to pick and which is default ('mine' default, 'shared' = granted access, 'open' = anyone can read/edit). There's no explicit 'use this instead of X' routing to get_presentation, but the when-to-use context is clear from the scope semantics.

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 useful scope context (your projects plus those you were granted access to, with presentations in order), but the trailing sentence about blocks leading to slides of other presentations is confusing and does not clearly describe this tool's 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?

The domain definition is front-loaded, which is reasonable, but the last sentence is opaque and arguably off-topic for a list operation, diluting otherwise compact prose.

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

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

With an output schema present and rich annotations, the description is not required to explain return values or safety, and it does supply the access scope. However, it omits any routing information among the many sibling tools and ends with a sentence that confuses rather than completes the picture.

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 for a parameterless tool.

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

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

The description defines what a project is ('presentations that belong together') and describes the scope of what is returned, but never states the action verb directly — the listing behavior is carried entirely by the name/title. It also does not distinguish this tool from siblings like get_project or list_presentations, so the agent must infer the distinction from naming alone.

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 guidance and no alternative named; nothing tells the agent to prefer get_project for a single project or list_presentations for presentations. The access-scope sentence implies coverage but not when this call is appropriate.

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

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

Annotations already declare it is a write (readOnlyHint=false), non-idempotent, and non-destructive, but the description adds genuinely new behavior: manually-set names are overwritten, slides without text are left alone, and the new name persists and re-follows later title changes. Disclosing the overwrite of hand-set names is valuable context beyond the safety hints, though it stops short of stating auth specifics or exact return shape.

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 behavior is front-loaded, but the prose is convoluted, especially 'the text block with the biggest letters (the highest one of those)', which forces the agent to parse a nested clarification. Every sentence carries information, but the structure is denser and more awkward than needed.

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 write tool with an output schema present, the description gives a thorough account of the algorithm, its persistence behavior, and its edge cases (hand-named slides, textless slides). The main remaining gap is the absence of explicit usage/alternative guidance, which is minor given the detailed behavior.

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 slug parameter is fully documented in the schema (100% coverage), including its /movie/<slug>/ format. The description adds no syntax or meaning beyond that, so the baseline 3 for schema-driven parameters 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?

The description names a specific verb (name) and resource (every slide of a presentation) and defines the mechanism precisely: the title is 'the text block with the biggest letters'. It is clearly distinguishable from generic siblings like update_slide or edit_slides, though it never explicitly contrasts itself with those.

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 the prerequisite 'a presentation you may edit', which conveys a permission requirement but not an explicit when-to-use or when-not-to-use rule. No alternative (e.g. update_slide) is named or routed to, so the agent must infer placement from the sibling list.

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 the safety profile (readOnly, idempotent, non-destructive, non-open-world), so the bar is lower. The description adds real context: rendering is done by a server-side browser, there is a hard 6-slide cap per call, selection prefers the first ids/ranges, and layout_warnings are returned from the same render.

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 purpose, then constraints and parameter behavior. Dense but every sentence carries information; no filler or restatement of the 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?

Output schema covers return values, yet the description still usefully notes that layout_warnings accompany the pictures. For a read-only 6-parameter tool with full schema coverage and an output schema, this is complete enough to call 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% so 3 is the baseline, but the description goes further by explaining the precedence between slide_ids and from_number..to_number, the slide-1 default, and the meaning of width in px. This interaction logic is not captured in the per-parameter schema text.

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 (render PNG pictures of slides exactly as viewers see them) and the reason it exists (check text fits blocks, blocks don't overlap). An agent can distinguish this from siblings like check_layout or get_slide 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?

Clearly frames the use case (visually verifying layout correctness) and gives an operational constraint (max 6 slides per call). It does not, however, explicitly name the alternative check_layout tool or state when to prefer a programmatic check over a visual preview.

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 genuine behavioral value by describing the nature of the returned content (person-like slide-by-slide reading, image descriptions, link destinations, and the 'card' aggregation concept), which goes beyond the 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?

Front-loaded with the core action and appropriately sized for a rich read tool. The parenthetical defining a 'card' is slightly tangential but earns its place by explaining a json output entry type.

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

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

With an output schema present, the description need not enumerate return values, yet it still conveys the shape of the content and the format trade-off. Combined with complete annotations and full schema coverage, an agent has enough to invoke it correctly; only sibling disambiguation 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% and every parameter (lang, slug, format, slide_ids, from_number, to_number) is documented in the schema itself. The description only restates the markdown-vs-json format distinction and the card concept, adding no syntax or behavioral detail beyond the structured fields, 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?

The description states a specific verb (read) and resource (presentation) and details exactly what 'reading' yields: slide-by-slide text in reading order, picture descriptions, code, and link targets. It is clear and concrete, but never names the obvious competing siblings (get_presentation, preview_slides, get_slide, export_presentation), so an agent cannot tell from the description alone why it should prefer this 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?

It gives an access precondition ('any presentation you can see (not private, or shared with you)'), which is useful scoping, but there is no explicit when-to-use-vs-alternative guidance despite several overlapping read tools in the sibling list. Usage is implied rather than stated.

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 is a non-readonly but non-destructive, idempotent mutation. The description adds genuinely useful behavioral context beyond that: the order array must contain ALL slides, implying full-replacement semantics where a partial list is invalid. It still does not say what happens if ids are missing or repeated (error vs. silent drop), 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?

A single compact sentence that front-loads the action ('Set the playback order') and then explains the key parameter. The nested colon-and-quotes construction is slightly awkward but wastes no 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. For a two-parameter idempotent mutation the description covers the essential constraint, leaving only the failure behavior for incomplete or invalid orders 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% and both parameters are documented in the schema, including 'Every slide id, once.' The description reinforces the same completeness constraint on 'order' but adds no new syntax, format, or edge-case detail, 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: set the playback order of a presentation's slides, identified by slug and an id list. It is clearly distinct from siblings like add_slide, delete_slide, and edit_slides, though it never names those alternatives explicitly.

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, no mention of prerequisites (e.g., needing the presentation to exist, or permissions), and no routing to alternative tools such as edit_slides for non-order edits. Usage is only inferable from the verb itself.

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?

Despite annotations covering the safety profile, the description adds substantial non-obvious behavior: formatting is preserved, phrases split by formatting are not matched, {{slide:N}} references are immune to replacement, and dry_run changes nothing. The extraction-by-formatting caveat and reference-number caveat are exactly the kind of hidden traits that prevent misuse.

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 purpose is front-loaded in the first clause, then productive caveats follow. It is dense with quoted parameter names and parentheticals, which costs a little readability, but every sentence carries 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 13-parameter mutation tool with 100% schema coverage, full annotations, and an output schema, the description fills the remaining gaps: return summary ('how many were replaced on which slides') and the tricky matching invariants. Nothing an agent needs to invoke it correctly 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, but the description adds semantics the schema lacks, notably that regex mode allows \1 backreferences in the replacement and that langs defaults to all languages. This elevates it slightly above the schema-only 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 precise verb (find and replace) plus the exact scope: text/shape/button blocks, slide names, and code blocks within a whole presentation in one step. This clearly separates it from the per-block/per-slide editors like edit_blocks and edit_slides.

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 conveys context clearly (whole-presentation bulk replace, dry_run to only count, regex mode) and even states when matching will fail (formatting-split phrases, {{slide:N}} references). It stops short of explicitly naming alternative tools for narrower edits, so not a full 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?

Annotations only declare the generic read/write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description adds the substantially more useful behavioral facts: the author approves or declines out-of-band, the granted access attaches to the account rather than the session, and a repeat call updates the pending request rather than erroring. That last point is consistent with idempotentHint=false.

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

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

Three sentences, front-loaded with the purpose, then mechanics, then the account-scoping and re-ask behavior. Nothing is padding, though the role recap in sentence one mildly duplicates the schema's enum descriptions.

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

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

With an output schema present, return values need not be described, and the description covers the async approval loop and the account-wide effect of a granted request. It omits edge cases such as already holding the requested role or requesting access to a slug that does not exist, which keeps it from 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 description coverage is 100%, so the schema already documents slug, role and message, including the enum glosses. The description restates the role semantics ("view" to read, "edit" to change) in prose but adds no format, constraint, or syntax beyond what the schema carries; 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 and resource (ask the author of a presentation for access) plus the two access levels it can request. It is clearly distinguishable from the sibling request_project_access, which targets a different resource, so an agent can select 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?

Explains the condition that selects each role value ("view" to read a private one, "edit" to change one that is not open), which is genuine when-to-use guidance. It does not name alternatives such as get_access or request_project_access, nor say what to do if access already exists, 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?

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds genuinely non-obvious behavior: the grant is request-based (an author must approve) and, once approved, persists to presentations added later. It does not say how the request is surfaced to the author or what happens while it is pending, which keeps it below 5.

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 target, then the role semantics, then the scope-of-approval consequence. No filler, no restatement of the title, and every clause 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 an output schema present, return values need not be described, and the description covers the action, both parameter effects, and the durable scope of the grant. It stops short of stating that access is not immediate (pending author approval) or how the requester learns of the outcome, which a request-style tool with idempotentHint=false would ideally clarify.

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, but the description adds meaning beyond the enum labels: "view" grants read of private presentations rather than mere metadata visibility, and the role applies project-wide rather than to a single item. It says nothing about the optional message parameter, but the schema already documents it.

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 (ask the project's author for access) and defines the scope of what is being requested, including that it covers every presentation of the project. It implicitly contrasts with the sibling request_access (per-presentation) via "access to all of it" and "counts for every presentation", but never names that sibling, so the differentiation is inference rather than explicit.

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 what the two roles mean and what approval grants (including future presentations), which implies when each role is appropriate. However, it gives no explicit when-to-use guidance relative to request_access, get_access, or set_access, and no preconditions such as needing to know the project slug or that a human must approve.

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 say destructiveHint=false and readOnlyHint=false; the description adds the authorization rule (who may resolve), which is exactly the kind of context annotations don't carry. It doesn't mention idempotency or reversibility explicitly, though the resolved:false path implies reversibility.

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: action + toggle first, permission rule second. Nothing wasted, though the permission clause is slightly under-integrated.

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 toggle with an output schema and full annotation coverage, the description covers what it does, the reopen path, and who can call it. Return values are covered by the output schema; idempotency behavior is the only minor 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 coverage is 100% and the schema already documents both comment_id and resolved (including the default true). The description restates the resolved:false toggle, adding a little semantic framing but nothing beyond the schema. 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?

States a specific verb (mark) and resource (a thread/note), and clarifies the toggle to reopen via resolved:false. Toggling resolve vs. open is distinguishable from sibling delete_comment or add_comment, though it doesn't explicitly contrast with them by 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?

Conveys the permission model – owner of the presentation or thread starter may do it – which is a real usage constraint. But it doesn't explicitly say when to choose resolve vs. reopen beyond the parameter flip, and names no alternative tools.

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

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

Annotations only give the generic mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuinely new behavioral context: the restore is itself a new version, so it is undoable the same way, and an edit permission is implied. That is useful disclosure beyond the structured fields, though auth requirements and failure modes remain unstated.

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, front-loaded with the action and scope, then the reversibility caveat. Every clause earns its place with no redundancy.

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

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

With annotations covering the safety profile and an output schema covering return values, the description supplies the key missing piece (undo semantics) and the edit precondition. It is complete enough to call correctly, with only minor gaps around permissions and error behavior.

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% (slug and number both documented in-schema), so the schema carries the parameter burden. The description adds no format or constraint detail beyond it; 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 ('make ... look exactly as it did') and resource (a presentation version), and enumerates the restored scope (slides, blocks, order, title). An agent can distinguish it from read-only siblings like get_version or list_history, though no sibling is named explicitly.

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?

'A presentation you may edit' implies an edit-permission precondition, and the tool's role (reverting to a prior version) is inferable from context. However, there is no explicit when-to-use guidance, no statement of when to prefer it over update_presentation/edit_slides, and no 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 only give generic hints (readOnlyHint=false, idempotentHint=false); the description adds the crucial side-effect model: sql/mongodb/redis/clickhouse mutate a persistent presentation-scoped database ('what you change stays in it'), while python/bash run sandboxed with no network and no retention. It also explicitly reassures the presentation itself is untouched, which is high-value context beyond the structured fields.

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?

Densely packed and front-loaded with the purpose, and nearly every clause carries information (language groups, persistence, sandbox, presentation safety). It is a single run-on sentence that would be easier to parse if split, which keeps it from a 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?

An output schema exists so return values need not be described, and annotations plus the description together cover the safety and side-effect profile. For a code-execution tool the agent has everything needed: what runs, where it runs, what persists, and what is left untouched.

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, but the description adds real meaning: it partitions the lang enum into two groups with distinct execution and persistence semantics that the schema's bare 'Language of the code.' does not convey. The reset parameter's effect is only covered by the schema, not the description, keeping it from a 5.

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 ('Run code the way the Run button of a code block does') and immediately scopes the intent ('to check it'). No sibling tool executes code, and the description makes that distinct role obvious 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?

The stated purpose ('to check it') clearly frames the use case for verification, and the language groups imply when each mode is appropriate. It offers no explicit when-not or named alternatives, but the tool is unique enough among siblings that this is a minor gap.

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=false, destructive=false and idempotent=false, so the safety profile is covered. The description adds real behavioral context beyond that: 'open' makes the history keep every change, 'public' separates read from edit rights, and 'revoke' strips usernames of access. It still omits prerequisites (e.g. owner-only) and reversibility.

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 front-loaded sentence that leads with the verb and resource before drilling into the level semantics. The quote-and-dash formatting is slightly dense but every clause carries information; nothing is wasted.

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

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

With an output schema present, return values need not be described, and annotations cover the safety profile. The description covers purpose and all three parameters, though it leaves prerequisites and the interaction between setting a level and pre-existing grants unaddressed.

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, but the description genuinely adds meaning the schema lacks: the schema only labels the enum values, while the description spells out who can read/edit under each level and the history side effect. This is useful semantic elaboration beyond the structured fields.

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: 'Change the access of your presentation', so the agent knows this is the mutator for presentation access. It does not explicitly contrast itself with siblings like get_access or request_access, but the verb+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?

The description never says when to use this tool versus alternatives such as get_access (read), request_access (ask for access) or answer_access_request. The level explanations describe parameter values, not tool-selection guidance, so an agent gets no routing help from the text.

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 readOnly=false, destructive=false and idempotent=false, and the description goes well beyond them. It explains exactly what happens to existing texts: translations are swapped, already-correct texts stay, and untranslated ones are listed. It also notes that counts and remaining translations are returned, giving strong behavioral context 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?

The description is front-loaded with the trigger condition and then explains the effects in a logical sequence. It is somewhat verbose and contains a parenthetical example that lengthens it, but every sentence contributes useful semantics for a complex mutation. It avoids repetition and unnecessary fields.

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?

An output schema exists, so the description need not detail return values, though it briefly mentions counts and untranslated items. Given the mutation's complexity, it covers what is changed and when to use it. The main remaining gap is that it does not reference the related translate_presentation sibling or other alternatives.

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 both parameters have descriptions in the schema. The description adds little parameter-level detail beyond what the schema already provides, so the baseline for high coverage is appropriate. It does not, for example, clarify slug format or the lang enum 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 verb and resource: declaring/repairing the language of a presentation's texts, slide names and title. It clearly distinguishes the operation from a simple metadata update by explaining the translation-swapping behavior. It does not explicitly name sibling tools such as translate_presentation, so sibling differentiation is helpful but not explicit.

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 condition for use: 'when the site guessed it wrong.' That is a concrete trigger and implies the tool is for correcting an incorrect language guess rather than general translation. It does not name an alternative or state when not to use it, so it falls just short of full routing 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?

Adds substantial behavior beyond the annotations: human/agent-authored translations are preserved while stale machine translations are regenerated, and the tool returns a count and answers 503 when no translator exists. This discloses what is mutated, what is protected, and error behavior, all consistent with the write/non-idempotent 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?

Front-loads the core purpose and then adds preservation, timing, and error facts, each earning its place. It is somewhat dense and run-on but contains 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?

With an output schema present, return values need not be explained, and the description already notes it 'says how many.' Combined with mutation scope, preservation rules, automatic-vs-manual timing, and the 503 condition, nothing an agent needs to call it correctly 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?

Only one parameter with 100% schema coverage; the schema already documents the slug fully (its address /movie/<slug>/). The description adds no syntax or format detail beyond that, so the 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 ('fill in, by machine translation') and precisely scopes the resource: title, slide names, and text/shape/button block texts of a presentation. No sibling tool performs translation, and the description makes clear it targets untranslated texts only, so an agent can distinguish it immediately.

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

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

Provides clear context for when to invoke: the site already does this automatically a few seconds after every change, so calling this tool means 'do it now.' That implicitly guides the agent toward manual use, though it never states an explicit when-not condition or names an alternative 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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) by disclosing non-obvious semantics: the theme only affects new slides/blocks and not existing ones, the slug never changes, omitted languages keep their scripts, and an empty string removes a script. It also surfaces the permission model (author-only for database scripts, edit rights otherwise).

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, front-loaded with the full set of changeable fields, followed only by two genuinely informative clarifications about theme scope and slug immutability. 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 an 8-parameter mutation tool with nested objects, an output schema, and 100% schema coverage, the description covers the important behaviors and constraints. It omits mention of title_tr and names_from_titles, but those are fully documented in the schema, so the gap is minor.

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% and the schema already explains each field in depth (theme defaults, per-language database scripts, empty-string removal, cover_slide null meaning). The description's theme and slug notes largely restate what the schema says, so it adds little parameter-level meaning beyond the 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?

States a specific verb (change) plus the exact resources it mutates: title, description, theme, cover, and database setup scripts of a presentation. This clearly separates it from update_slide, edit_slides, edit_blocks, and update_project without the agent needing to open 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?

Gives a real precondition — the presentation must be one 'you may edit', and the database scripts are changeable by 'its author only' — which tells the agent when the call will succeed. It does not, however, name alternatives or say when not to use this tool (e.g. versus name_slides_after_titles, which overlaps the names_from_titles parameter).

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