Aitho

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

Annotations already declare non-read-only, non-idempotent, open-world behavior, and the description adds genuinely new traits: text is extracted and used for answering, failures are reported per document with a reason, and partial success still adds the rest. That partial-failure semantics is the key behavioral detail an agent needs and it is not derivable from 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?

Three sentences, front-loaded with what the tool does before the per-document outcome and the plan requirement. Dense but every sentence adds an operational fact; 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 no output schema, the description usefully explains the return shape (per-document success/failure reporting) and covers prerequisites. Only minor gaps remain, such as size/count limits or default naming behavior, which are unlikely to block a correct call.

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

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

Schema coverage is 50%: the documents array shape ({url, name?}) is already documented in the schema, and the description only reinforces the URL-based input by listing formats. talk_id is undocumented in both places. Baseline 3 is appropriate since the schema carries most of the parameter burden.

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 (adds), resource (grounding documents for Q&A), transport (by URL), accepted formats, and target scope (an existing talk's private Q&A). It is clearly distinguishable from siblings like remove_qa_document, list_qa_documents and aitho_attach_script.

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 makes the use case clear (supplying grounding material to answer audience questions) and gives a real prerequisite: Presenter Pro, with the one-talk exception for free accounts. It stops short of naming a sibling alternative or an explicit when-not-to-use case, so it is strong context rather than 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?

Goes well beyond the destructiveHint/idempotentHint annotations: it discloses the length-mismatch rejection with an example error, the empty-string semantics, the per-clip narrate_over behavior, and a Presenter Pro entitlement requirement. The 'attaches or replaces' wording is consistent with destructiveHint=true.

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 purpose before mechanics and every sentence carries information (error format, ordering, entitlement). The single dense block is long, but there is little 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 no output schema, the description still tells the agent what happens on failure, how to obtain the required slide count (aitho_get_talk), and the entitlement constraint. Nothing needed to invoke this 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 only 67% and talk_id is undocumented, but the description compensates for the key parameter by explaining the index mapping (entry i -> slide i+1), the meaning of empty strings, and the absence of in-text slide markers — real meaning beyond the schema. The clips semantics largely duplicate the schema description.

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 ('attaches or replaces the speaker script on an existing talk') and scopes the content type (speaker notes, talk track, teleprompter script). It does not distinguish itself from the sibling set_script, which an agent could plausibly confuse it with, so it falls short of a 5.

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

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

Clearly frames when this applies ('for speaker notes, a talk track or a teleprompter script... including shortening, retiming or rewriting'), which is concrete usage context. However it offers no explicit when-not or alternative routing (e.g. vs set_script), so it stops 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?

Beyond the annotations, it discloses that the call returns immediately with talk_id and status while parsing/extraction run asynchronously, names the tool that reports progress, explains the gamma server-side export and its dedup behavior, notes that upload_id bytes never traverse the conversation, and states the Presenter Pro entitlement plus the free-account limit of one talk. This is substantial behavioral context the structured fields do not carry.

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 use case and the primary deck-source decision are front-loaded, and nearly every sentence carries load-bearing information. It is, however, a single very dense paragraph with multiple nested asides (token cost, gamma dedup, entitlement tiers), which makes it harder to scan than a lightly structured version would be.

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

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

With no output schema, the description still covers the return value (talk_id and status), the asynchronous follow-up path, the deck-source decision, the optional script and grounding documents, and the permission requirement. An agent has everything needed to invoke it correctly and to know what happens next.

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%, so the baseline is 3, but the description adds a constraint the schema cannot express: the three deck sources are mutually exclusive ('exactly one of'), which matters because the schema marks zero parameters required. It also clarifies the narrate_over semantics and the gamma URL handling, though much of the per-parameter detail duplicates the rich schema descriptions.

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 — 'Creates a talk ... from a PDF, PPTX or PPT deck' — and enumerates the use case (rehearsing/delivering a presentation) so an agent can tell it apart from sibling tools like aitho_prepare_upload, aitho_attach_script, and aitho_get_talk. It also scopes the deck sources precisely, leaving no ambiguity about what is being created.

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

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

It gives explicit when-to-use framing ('For rehearsing or delivering a presentation ... including a deck made earlier in the conversation') and enforces the mutual-exclusivity rule: 'The deck comes from exactly one of: deck_upload_id ... deck_file ... deck_url'. It routes the agent to the prerequisite tool (aitho_prepare_upload) and to the follow-up tool (aitho_get_ingest_status), and explains the size tradeoff that selects deck_upload_id over deck_file.

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 semantics, so the safety profile is covered. The description goes beyond that by enumerating the stage progression, error_code taxonomy, and expected completion time, which is useful operational context; it omits any note on staleness or whether repeated polling is expected.

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

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

Purpose and returned fields are front-loaded in one dense sentence, with the timing note as a useful standalone closing sentence. Slightly over-stuffed mid-sentence with the long error_code enumeration, but 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 no output schema, the description carries the return-value burden and does so thoroughly for a single-parameter tool: status values, per-stage detail, failure codes, and timing. Only a polling-cadence or staleness hint 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 0% and the description never describes talk_id either, so neither source documents the parameter. The name is self-evident as the identifier of the talk, which keeps this at a baseline 3 rather than lower, but the description does nothing to compensate for the gap.

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

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

A specific verb and resource and an explicit universe of returned fields, tied back to aitho_create_talk. It does not explicitly distinguish itself from the sibling aitho_get_talk, so an agent must still infer which of the two to call for general talk data versus ingest progress.

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 'of a talk created with aitho_create_talk' and the timing note hints at polling, but there is no explicit instruction to poll repeatedly, no when-not-to-use, and no routing advice against aitho_get_talk. Adequate but leaves the agent to infer the call pattern.

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 (readOnlyHint, idempotentHint, destructiveHint=false, closed world), so the description's job is to add what they can't. It does this well by disclosing the return contents: per-slide {slide, text, hasScript, script}, title, slide count, attached Q&A names. That is genuinely useful since no output schema exists.

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

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

Two sentences, front-loaded with purpose before the return-shape detail, and no filler. The return-shape sentence is dense but every clause carries information an agent needs given the absent output schema.

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

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

For a simple single-parameter read tool with no output schema, the description supplies the missing return contract and the intended use case. Only omission is how to source talk_id, which is a small gap for an otherwise complete definition.

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

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

Schema description coverage is 0% and the single required parameter talk_id is never elaborated in the description (no format, source, or how to obtain it). With one self-evident identifier this is a minor gap, but the description adds no meaning beyond the schema's type declaration.

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 ('reading the real text of every slide in a talk') and signals the use case (speaker script, practice questions). It implicitly distinguishes itself from get_script and get_deck by focusing on slide text, but never names those siblings explicitly, so the differentiation is inferred 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?

Gives clear when-to-use context: as the basis for writing/reviewing a speaker script or building practice questions. It does not name alternatives (e.g. get_script for script-only reads, list_talks for discovery) or state when-not-to-use, so it stops 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by enumerating the returned fields (id, title, slide count, created date) despite no output schema, and by clarifying filter/match semantics; it omits any pagination defaults or limits on the limit value.

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 compact sentences, front-loaded with the use case before behavior and parameters. The final sentence largely restates the schema, which is mild redundancy, but there is no padding overall.

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-required-parameter read tool with no output schema, the description supplies the missing return-field list and filter behavior, which is what an agent needs to call and interpret it. It stops short of noting default limits or ordering of results.

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

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

Schema coverage is 100%, so both parameters are already documented as 'Max talks to return.' and 'Optional case-insensitive title filter.' The description repeats those same facts ('filters titles case-insensitively', 'caps the count') without adding syntax, defaults, or maximums, 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 (lists) and resource (talks/presentations) with an explicit account scope and a stated purpose (finding a presentation by title). It is clear what the tool does, but it never names a sibling such as get_talk, so the differentiation from single-talk retrieval 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?

The opening sentence gives a concrete use case — locating a presentation the user already has by its title — which is clear context for invoking it. There are no exclusions or named alternatives (e.g., 'use get_talk when you already know the id'), so it stops 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?

Goes well beyond the annotations: the ticket belongs to this account, expires in 15 minutes, is single-use and consumed on talk creation, is never a public link, and requires the same Aitho authorization header on the PUT. It also explains the side-effect-free transport (bytes bypass the conversation). The annotations only declare non-readonly/non-idempotent; the description supplies the real operational constraints.

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

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

Four dense sentences, front-loaded with purpose and immediately followed by the return values and the handoff to aitho_create_talk. Every sentence carries new information (auth header, size/length tradeoff, expiry semantics), though it is longer than strictly minimal.

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

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

With no output schema, the description still documents both return values and their meaning, plus lifecycle (expiry, single-use, consumption) and the required follow-up call. Nothing an agent needs to invoke and chain this tool 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% for the single filename parameter, so the schema already documents it fully. The description restates the accepted extensions (.pdf, .pptx, .ppt) without adding format or syntax detail beyond the schema, 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 ('prepare ... deck upload') and precisely what it produces: a short-lived single-use upload_url and upload_id for one deck file. It clearly distinguishes itself from siblings by naming aitho_create_talk as the consumer of upload_id, so an agent knows this is a pre-step, not the talk creation itself.

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 context for when to call it (user attached a deck, or a deck was made in the conversation) and explicitly routes the output to aitho_create_talk via deck_upload_id. It does not state a 'when not to use' or contrast with an alternative upload path, which keeps it 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?

Goes well beyond the annotations: it discloses the answer-sourcing order (deck material and attached Q&A documents first), a fallback live web lookup, and the cost implication that the lookup 'counts against the plan's monthly web-lookup meter'. That cost/side-effect disclosure is exactly the additional context annotations cannot carry.

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 purpose and answer behavior in two tight sentences, with no filler. The prerequisite and metering caveat arrive later, which is slightly suboptimal ordering but still an efficient four-sentence description.

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

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

No output schema exists, and the description does explain the return ('returns the answer') plus the sourcing/cost behavior, so an agent has what it needs to invoke it. Missing latency/async expectations for the web-lookup path 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 coverage is 0% for the single 'question' parameter, but the description supplies the semantic frame: the question is posed against the deck's material and answered from it. For a lone, plainly named string parameter this is adequate, though no format or length guidance is given.

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 ('Sends a question to the active deck's private Q&A and returns the answer') and scopes the answer source to the presenter's slides/documents. This clearly separates it from sibling document-management tools like list_qa_documents or remove_qa_document.

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 concrete use case (practising questions after a talk, pitch or defense) and a hard prerequisite ('Requires an active presentation'). It does not name an alternative tool or state when NOT to use it, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description still adds real value beyond them: the exact-match confirmation guard, the refusal behavior on mismatch, the active-presentation restriction, and the 30-day purge window. That is precisely the behavioral context 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?

Front-loaded with the action, then the recovery window, then the guard conditions, then the return value. Nearly every clause adds a distinct operational fact, so the density is earned rather than 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?

For a two-parameter destructive tool with no output schema, the description covers the recovery path, the guard condition, the blocking case, and the returned trash_id. Nothing an agent needs to call this safely 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 only 50%, so the description has to carry weight: it explains that confirm_title is the user's confirmation and must exactly match the deck's current title, with a refusal on mismatch. The slug parameter is never explained, leaving one of two parameters undocumented in both schema and description.

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 (moves) and resource (deck, with its constituents), and immediately distinguishes the operation from its inverse by naming restore_deck as the recovery path. An agent can separate this from remove_qa_document or list_trash 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?

Gives explicit preconditions and exclusions: confirm_title must exactly match the current title or the call is refused, and the active presentation cannot be deleted. It also states the 30-day recoverability window, which tells the agent when this is the right tool versus a permanent removal path.

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 covered by structured data. The description adds meaningful behavioral context by defining what the cue map means (segment-to-slide correspondence by index), but says nothing about how alignment is produced, whether it can fail/mismatch, or what the map looks like when empty.

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

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

One tight sentence that front-loads the returned entity and then qualifies it with the mapping rule. No filler, though the parenthetical could carry a bit more payload for the space it takes.

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

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

With no output schema, the description must convey the return shape; it does sketch the cue map structure, which is the most important thing here. It is still incomplete on parameter meaning (slug) and on edge cases such as missing or unaligned scripts.

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

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

Schema description coverage is 0% and the single parameter 'slug' is undocumented in the schema. The description never mentions 'slug' or explains that it identifies the talk/deck, so it does not compensate for the coverage gap.

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

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

States a specific verb ('Returns') and a specific resource ('the cue map that links each script segment to its slide'), and even discloses the mapping rule ('segment i drives slide i'). It is clearly not the same as get_script or get_deck, though it does not name a sibling to reinforce the distinction.

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, when to use get_script/get_deck instead, or any prerequisite (e.g. that a script must already be attached). The agent must infer the use case entirely from the purpose sentence.

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 destructiveHint=false, covering the safety profile. The description adds valuable context beyond annotations by specifying what data is returned (metadata, per-slide summary, script presence, Q&A count, preview) and explicitly stating that slide images are NOT included, which prevents an agent from assuming it can retrieve image content. It does not cover pagination or error behavior, but for a read-only summary tool the disclosure is above average.

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 sentence delivering purpose, contents, and exclusions with zero waste and front-loaded information. 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?

For a one-parameter read-only tool with no output schema and annotations covering safety, the description is nearly complete: it tells the agent what the return contains and what it omits. The only minor gap is not clarifying what 'script preview' means (length, format), but an agent can invoke correctly without that detail.

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

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

Schema description coverage is 0% and there is only one parameter (slug) required. The description does not name or explain the slug parameter, but with zero params documented in the schema the description still adds the key semantic of what the deck is by reference to its slug (the deck's summary). Given the single required parameter and its conventional name, the absence of explicit semantics is a minor gap; baseline for missing param info with low coverage would be lower, but the low complexity and conventional name justify a 4.

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 (returns) and resource (deck metadata and per-slide summary), and enumerates exactly what is included: script presence per slide, Q&A document count, script preview. An agent can distinguish this from siblings like get_script (which returns script content) or list_decks (which lists decks) 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?

The description implies the tool is for retrieving a summary view of a deck, and it explicitly notes that slide images are not included, which tells the agent when this tool is insufficient. However, it does not name alternatives (e.g., get_script for full script content) or state any preconditions (e.g., deck must exist, slug format). Usage context is implied but not explicit.

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 genuine behavioral context beyond them: the return is an array indexed by slide ('entry i is the script for slide i') and the range params are 1-indexed and inclusive, which the annotations do not 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 compact sentences, front-loaded with the return semantics before the optional filtering detail. No filler and nothing redundant with the schema or annotations.

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

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

With no output schema, the description usefully specifies the return shape (per-slide array) and the indexing base, which is exactly what an agent needs to interpret results. Only the slug parameter and any edge cases (e.g., behavior when a slide has no script) are 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 0%, so the description must carry parameter meaning, and it does for the two optional params ('1-indexed, inclusive' range limiting). It does not explicitly describe slug, though its role is obvious from context, so it falls just short of fully compensating.

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 ('Returns the deck's per-slide speaker script') and clarifies the resource further with the parenthetical 'teleprompter text'. The entry-i-is-slide-i mapping makes it clearly distinct from the set_script sibling and from get_deck.

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 use this tool versus alternatives such as get_deck or set_script, and no prerequisites or exclusions. The only guidance is indirect, via the optional range parameters, so usage must be inferred from the name and sibling set.

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 behavior, so the bar is lower. The description adds genuinely new context by specifying the return shape: a 1-indexed slide number and a phase value constrained to 'present' or 'qa'.

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

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

A single sentence with zero waste; the return contents are front-loaded immediately after the verb, so an agent can decide relevance at a glance.

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 no-arg read tool whose annotations cover the safety profile; the description compensates for the absent output schema by documenting exactly what is returned. Only the lack of usage context keeps it short of full marks.

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?

Zero parameters, so per the baseline this starts at 4. There is nothing for the description to disambiguate and the schema is trivially complete.

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 ('returns the live state of the active presentation') and names the returned fields (current slide, phase). This distinguishes it reasonably from static-content siblings like get_deck, though it never explicitly contrasts with them.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as get_deck or get_alignment. The agent must infer the context from the tool name alone.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the mutation, safety and idempotency profile is covered. The description adds the important 1-indexed addressing convention, but says nothing about what happens on out-of-range slides or whether an active presentation is required.

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

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

A single sentence that front-loads the action and packs the essential indexing detail with zero filler.

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

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

For a trivial single-parameter navigation tool whose annotations already cover safety and idempotency, the description is nearly sufficient. The main residual gap is stating that a live presentation must be active and how invalid slide numbers are handled.

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

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

Schema description coverage is 0%, so the schema alone leaves 'slide' undocumented. The description partly compensates by specifying the indexing base (1-indexed), which is the key semantic an agent needs, but omits valid ranges or error behavior for invalid indices.

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 (Moves) plus resource (the live presentation) and target (the given slide), with the 1-indexed convention stated inline. It is clearly distinguishable from next_slide/previous_slide by 'the given slide', though it does not name those siblings 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?

'Live presentation' implies this only applies while a presentation is running, giving implied context for use. However, there is no explicit guidance on when to use this versus next_slide or previous_slide, and no exclusions or prerequisites are 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's main added value is disclosing the return shape (slug, title, slide count), but it says nothing about ordering, default limit behavior, or whether results are paginated.

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

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

Two tight sentences with zero padding; the return fields are front-loaded before the optional parameters. Every clause carries information the agent can act on.

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

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

With no output schema, the description correctly compensates by naming the returned fields. It remains slightly incomplete on ordering, default limit when omitted, and whether a total count or truncation indicator exists — minor gaps for a simple read-only list tool.

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

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

Schema description coverage is 100%, so both parameters are already documented (limit = max decks, query = case-insensitive title filter). The description restates both with a matching example, adding semantic confirmation but no new syntax, defaults, or edge-case behavior. Baseline 3 applies 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 specific verb+resource ('Lists the presentation decks in this Aitho account') and even enumerates the returned fields (slug, title, slide count), so the agent knows exactly what it gets. It does not, however, distinguish itself from lookalike siblings such as aitho_list_talks or get_deck.

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 — the agent infers this is the enumeration tool and get_deck is the single-deck counterpart, but the description never says so. The only explicit guidance concerns what the two optional params do, not when to reach for this tool versus a sibling.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the useful context that these are private Q&A attachments, but discloses nothing about return shape, ordering, or pagination, so it earns a modest 3.

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

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

Two short sentences with the purpose front-loaded are efficient, but the trailing sentence 'The Q&A answers from the deck plus these documents' is syntactically ambiguous and could be read as describing the return value or the feature rather than the tool behavior.

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

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

For a simple read-only list tool whose annotations cover safety and with no output schema to explain, the description is minimally adequate. It nonetheless omits what the parameter means and what a caller receives, which are the two remaining gaps an agent would want filled.

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

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

Schema description coverage is 0% and the description never mentions the sole parameter 'slug' or that it identifies the target deck. With low coverage the description is expected to compensate, and it does not, leaving the parameter undocumented in both structured and unstructured 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?

The description gives a clear verb ('Lists') and a specific resource ('supporting documents attached to a deck's private Q&A'), with an example (RFP) that grounds the concept. It is distinct from most siblings, though it never names its natural counterpart remove_qa_document or aitho_add_documents to sharpen the boundary.

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, no prerequisites (e.g. the Q&A feature must exist or be enabled), and no mention of the sibling alternatives for adding or removing documents. Usage is only inferable from the verb.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description's added value is the 'purged after 30 days' retention policy plus the returned fields — genuine behavioral context an agent cannot get from the annotations. It omits auth requirements and pagination/volume behavior, keeping it at 4.

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 its scope, followed by the retention constraint. No filler or repetition, though the field enumeration is slightly list-like rather than 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?

For a zero-parameter, read-only list tool with no output schema, the description covers what is returned and the 30-day purge window. Missing only auth/pagination context, which is minor at this complexity level.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the schema-coverage metric is moot. Per the rubric, 0 params yields a baseline 4.

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 — 'Lists decks in the trash' — and enumerates the returned fields (trash_id, title, deleted_at, restore_until), which implicitly separates it from list_decks (active decks) and get_deck. It stops short of explicitly naming the sibling it is not, so it earns a 4 rather than 5.

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

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

Usage is only implied: the tool surfaces trashed decks and their restore_until dates, which suggests a pre-restore workflow, but the description never says when to call this instead of list_decks or get_deck, nor routes to restore_deck. Implied usage only, so a 3.

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, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the stateful nature of the call is covered. The description adds useful context by scoping the action to a "live presentation" (a running session rather than a stored deck), but it says nothing about behavior at the final slide or when no presentation is active.

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 twelve-word sentence with the action and target front-loaded and zero filler. There is no structural waste to trim.

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

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

With no parameters and no output schema, the surface area an agent must understand is small. Still, the description omits failure conditions (no active presentation, already at last slide) that would matter for a stateful navigation call, leaving the definition merely adequate rather than 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter-level meaning is missing because none exists.

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 ("Advance") and resource ("the live presentation") with an explicit increment ("by one slide"). It implicitly distinguishes itself from goto_slide and previous_slide, though it never names those siblings to make the contrast 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 word "Advances" implies a forward-only navigation step, so usage is inferable, but the description gives no explicit when-to-use guidance and never mentions the obvious alternatives (previous_slide, goto_slide) or preconditions such as requiring an active live session.

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, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the mutation profile is covered structurally. The description adds that the target is the *live* presentation (not a stored deck), which is genuine context, but it omits what happens at the first slide (clamp vs. error) or whether an active session is required.

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 no wasted words. The scope qualifier 'live' appears early and the action is immediately clear.

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 no-argument navigation action with no output schema and annotations covering the safety profile, this is close to sufficient. The remaining minor gap is the absence of any note about session prerequisites or boundary behavior at the first slide.

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 and the baseline of 4 applies. No parameter-related information is missing.

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 (moves back) and resource (the live presentation, one slide), so the direction of navigation is unambiguous. It implicitly contrasts with the next_slide sibling, but never names that alternative to make the distinction 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 phrase 'live presentation' implies usage during an active session rather than deck editing, which is useful routing context. However, there is no explicit when-to-use guidance, no statement of prerequisites (an active presentation must exist), and no named alternatives such as goto_slide or next_slide.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the removal semantics and repeat-call safety are covered structurally. The description adds only the pointer that names come from list_qa_documents; it says nothing about what happens if the name does not exist, whether permissions are required, or whether the deletion is recoverable.

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

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

A single tight sentence with the action front-loaded and no filler. Every clause (scope, name source, containing location) 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 no output schema and annotations covering the destructive/idempotent profile, the essentials are present. However, for a destructive multi-tenant operation on a two-required-parameter tool, the definition leaves error behavior and the role of 'slug' 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 description coverage is 0%, so the description must carry the parameter burden. It does explain that 'name' is the document name as returned by list_qa_documents, which is genuinely useful, but it never explains that 'slug' identifies the deck, leaving one of two required parameters to inference.

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

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

The description states a specific verb and resource ("Removes one supporting document... from a deck's private Q&A"), and the explicit reference to list_qa_documents clarifies what kind of document is targeted. It largely distinguishes itself from the sibling list_qa_documents, though it does not name its natural counterpart aitho_add_documents.

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 rather than stated: you call it when you want to delete an existing supporting document, and the description usefully points to list_qa_documents as the way to discover valid names. There is no explicit when-not-to-use guidance and no mention of alternatives or preconditions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful scope context: only the display title changes and the slug is preserved, which bounds what the 'destructive' hint actually affects. It does not mention permissions or whether the change is reversible after the call, keeping 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 short sentences, zero filler, with the core action front-loaded and the important invariant (slug unchanged) immediately after.

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 mutation whose annotations already carry the safety profile, the description covers the essential scope question. Only minor gaps remain (auth requirements, response behavior), which is acceptable with no output schema.

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 0%, so both parameters are undocumented in the schema. The description partially compensates by mapping slug to the stable identifier and title to the display title, but adds no format, length, uniqueness, or validation details an agent would need.

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: changes a deck's display title, explicitly limited to title (not the slug). An agent can distinguish it from delete_deck, get_deck, or list_decks, though no sibling is named directly.

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 use this versus alternatives (e.g., set_script, create_talk) and no prerequisites or exclusions. The rename intent is self-evident from the verb, but nothing guides tool selection.

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

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

Annotations already declare this is a non-destructive, idempotent write. The description adds a genuine behavioral nuance beyond them: if the original slug is now taken, the restored deck gets a new slug. Auth/permission requirements and failure modes are not covered, so 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?

Two sentences, no filler, operation stated first, then the caveat that affects the caller's expectations. 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?

No output schema exists, yet the description covers the critical non-obvious return behavior (possible new slug) and the input's provenance. For a single-parameter restore tool this is close to complete, with only error/permission cases 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?

With 0% schema description coverage, the description carries the burden. It names trash_id and identifies its source tools, which is meaningful semantics the schema lacks, though it doesn't specify the id's format or whether it expires.

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 ('Restores a deck from the trash') with the keying parameter, which cleanly separates it from delete_deck, list_trash, and get_deck among the 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 tells the agent where the required input comes from ('from delete_deck or list_trash'), which is the main precondition for calling it. It stops short of stating exclusions, e.g. that only trashed decks can be restored or what happens if the deck was never trashed.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds concrete context: the previous script is overwritten and live voice-following switches to the new one. It also discloses an auth/tier requirement (Presenter Pro with a stated exception), which the annotations do not cover.

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

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

Two tight sentences with the core action front-loaded and the overwrite/voice-following behavior following. Efficient, though the Presenter Pro caveat is slightly crammed into the closing clause.

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

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

For a two-parameter mutating setter with no output schema, the description covers the essential behavior: full overwrite, per-slide ordering, downstream effect on voice-following, and the licensing requirement. The only gap is clarification of the undocumented 'slug' parameter.

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

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

Schema coverage is 50% — only 'script' is documented in the schema, while 'slug' is not. The description reinforces the array semantics ('one string per slide, in order') but adds nothing about what the 'slug' identifier refers to or accepts, so it only partially compensates for the gap.

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

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

States a specific verb ('Replaces') and resource ('the deck's entire speaker script'), and clarifies scope as a full per-slide array in order. An agent can distinguish this from get_script and aitho_attach_script by the 'entire script' scope.

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 establishes scope (entire script vs presumably attaching) and gives a real prerequisite ('Requires Presenter Pro, except on the one talk a free account created this way'), but never explicitly names an alternative tool or the condition that selects one over the other. 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 declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description's job is to add context. It usefully discloses the state change: the deck becomes active and is rewound to slide 1, which explains the idempotency and the mutation. It does not state error behavior or what happens if the slug is invalid, keeping it short of 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?

Three sentences, each with a distinct role: use case, mechanism/state change, then dependency note. Front-loaded with purpose and free of filler. Slightly more sentence overhead than strictly needed but nothing wasteful.

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

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

For a one-parameter activation tool with no output schema, the description covers what it does, the resulting active-presentation state, and which sibling tools depend on it. Missing edge-case behavior (unknown slug, auth) keeps it from being fully 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 0% and the single 'slug' parameter is undocumented in both schema and description. 'Makes a deck the active presentation' only weakly implies that slug identifies the target deck. With just one parameter and an otherwise self-evident identifier name, this is a modest gap rather than a severe one.

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 ('Makes a deck the active presentation and rewinds it to slide 1 in the present phase'), and distinguishes itself from siblings by noting that ask, goto_slide, next_slide and previous_slide operate on the presentation it activates. An agent can tell this is the 'activate' tool apart from the navigation tools.

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?

Opens with clear context – 'For rehearsing or presenting a talk, and for practising Q&A with ask' – telling the agent when this tool is appropriate. It names the downstream tools but does not give explicit exclusions or a when-not-to-use condition; there is arguably no alternative tool for activation, so 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.