Sparka

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

Annotations already mark this as read-only, idempotent, and non-destructive, but the description adds meaningful behavior beyond them. It explains the session-counting rule, the free-rehearsal implication, the billing boundary, and the instruction to share links rather than open them.

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 and most sentences carry useful context, especially the counting rule and usage guidance. The opening enumeration of return fields is somewhat redundant with the output schema, so it is slightly longer than strictly necessary.

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?

Given a zero-parameter read tool with a rich annotation profile and an output schema, the description is complete enough to call correctly. It covers purpose, timing, quota behavior, billing scope, and link-handling guidance.

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?

This tool has zero parameters, so there are no parameter semantics to clarify. The baseline for a zero-parameter tool is 4, and nothing in the description is needed to compensate for missing schema 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?

The description gives a specific verb and resource: returns the account's plan, limits, usage, summary, and pricing_url. It is clearly distinct from the deck/presentation siblings, so an agent can identify this as the account metadata tool 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?

It explicitly names when to use it: before writing a deck to check limits, or when a quota or participant-limit error occurs. It also sets a clear boundary that billing is managed on the Sparka account page, not through this 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context beyond annotations: Sparka ships no script library, the deck's own code is the integration, the reference code's look can be adapted, and no account key 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?

The description is front-loaded with the core purpose and then enumerates the covered topics. The first sentence is long and dense, but the enumeration is relevant for a guide tool and every clause contributes useful scope 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?

An output schema exists, so the description need not explain return values in detail. Annotations cover the safety profile. The main gap is the unexplained 'part' parameter, but otherwise the description gives enough context for an agent to understand what the tool provides.

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 input schema has one parameter, 'part', with an enum of all/rules/reference_code/html_skeleton, but schema description coverage is 0%. The description never mentions this parameter or explains that the guide can be requested in parts, so it fails to compensate for the missing schema documentation.

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: it returns the rules and a reference JavaScript pattern for making an HTML presentation interactive with Sparka. It clearly distinguishes this guide tool from the sibling CRUD tools for accounts, presentations, questions, and results.

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 clear this is the integration guide for building an interactive deck, and notes that no account key is needed. It does not explicitly name alternatives or when-not-to-use conditions, but the context is sufficiently clear for an agent to select it over the sibling 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 already declare destructive/idempotent/openWorld, but the description adds real substance: a running live session is terminated, past results remain readable via sparka_results_get by session_id until retention ends, and decks using the ID stop working. It also explains the ID-never-rotated workaround and the user-confirmation requirement, none of which is in the 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?

The permanent-delete action and its session side effect are front-loaded; subsequent sentences cover consequences, recovery of results, and the ID-retirement recipe. The parenthetical is dense but carries non-obvious operational guidance, so no sentence 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 destructive one-parameter tool with an output schema and full annotation coverage, the description supplies everything an agent needs: consequences, safety confirmation, downstream breakage, and how to recover results. Return values are correctly left to the 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% (the pattern is the only constraint), so the description must carry meaning — and it does, by explaining that the presentation_id is permanent (IDs never rotate), that dependent decks break on delete, and how to obtain a fresh ID. It stops short of saying where to source the ID (list/get), leaving one small 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 and resource ("Permanently deletes a presentation") plus the scope of what else ends (live session). It is clearly distinguishable from siblings like sparka_presentation_save, sparka_presentation_get, and sparka_presentation_list.

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 beyond simple removal (retiring an over-shared ID) with an explicit follow-up procedure, and states the prerequisite to confirm with the user first. It does not explicitly say when to prefer an alternative (e.g. save/edit instead of delete), so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds genuine context the annotations lack: the conditional redaction of correct answers and the inclusion of live-session and recent-session data, which matters for privacy/decision-making. It doesn't discuss errors or behavior when no live session 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 what is returned, followed by when to use it. The enumeration of returned sections is dense but every element is informative rather than padding.

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

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

An output schema exists, so the return-value enumeration is technically redundant, but the usage workflow and include_answers behavior make the definition callable as-is. Minor gap: no mention of what happens for an invalid or missing presentation_id.

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 the description must carry the parameter burden, and it fully explains the only non-obvious parameter — include_answers defaults to true and suppresses correct answers when false. presentation_id is only implied via the save workflow wording, but its name and the schema pattern make it self-evident.

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 one presentation") and enumerates what the single record contains, which cleanly separates it from the sibling sparka_presentation_list. An agent can tell it is a single-record fetch 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 two concrete use cases and names the follow-up sibling (sparka_presentation_save with the same presentation_id) for the edit workflow. It does not explicitly contrast against sparka_presentation_list or sparka_results_get, so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the description focuses on what annotations can't cover: sort order, the projected fields, and cursor pagination. It adds genuine value, though it omits page-size behavior and what happens at the end of the result 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 tight sentences: capability and ordering first, the disambiguating use case second, pagination last. No filler and nothing buried.

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-shape explanation isn't owed, and the safety profile is covered by annotations; the description covers ordering, pagination and selection intent. A brief note on default/max page size would close the remaining 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 50%: `cursor` is documented in the schema and merely restated by the description's "Paginated with `cursor`", while `limit` is undocumented in both places beyond its numeric bounds. Acceptable baseline, but the description does not compensate for the gap by explaining the page-size tradeoff.

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 ("Lists the account's presentations") plus ordering ("newest first") and the fields returned. It doesn't name sibling tools explicitly, but the phrase "without giving its ID" functionally separates it from sparka_presentation_get.

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?

"Useful when the user refers to a presentation without giving its ID" gives a concrete trigger condition with an example utterance, which is exactly the kind of routing signal an agent needs. No explicit when-not or named alternative, 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 flag destructiveHint=true, but the description goes well beyond them: it explains that replacement preserves the presentation ID, that unchanged question IDs keep matching slides, that answers are stripped from what the deck exposes, that questions are publicly readable by anyone holding the presentation_id, and that the secret key must never be embedded. It also discloses return contents and that validation failures return JSON paths.

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 create/replace contract, then return values, then deck-integration warnings. Every sentence carries operational information, though the embed_block/secret-key passage drifts toward deck-authoring guidance that sparka_deck_guide arguably owns.

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

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

For a destructive full-replace tool with nested question types and an output schema, the description covers the mutation semantics, ID stability, answer-stripping, return shape, and the failure mode. An agent has everything needed to call it correctly without trial and error.

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%, but the description compensates for the key top-level params: it defines presentation_id as omit-to-create/pass-to-replace, and states that questions must be the COMPLETE ordered list carrying correct answers for scored types. The title and settings params are left wholly to the schema, so it is not quite 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?

Opens with a specific verb+resource pair ('Creates or fully replaces a presentation's interactive questions') and immediately clarifies the create-vs-replace split on presentation_id, which cleanly separates it from sparka_presentation_get/list/delete 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?

Explicitly states both modes and when each applies ('Without presentation_id it creates a new presentation; with it, it replaces that presentation entirely'), and routes the agent to siblings for adjacent needs: sparka_question_types_list for valid types/fields and sparka_deck_guide for the deck JS 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 declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: no account key is needed, the result is filterable, and scored answers stay server-side and never appear in the deck. It does not discuss pagination or result size, which is a minor omission for a full-catalog listing.

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 opening sentence front-loads purpose and return content efficiently. However, the middle portion about id slug regex, uniqueness, stability across edits, and prompts describes constraints on sparka_presentation_save rather than this listing tool, which makes the description longer than its own job requires.

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 the description still covers auth requirements, filtering behavior, and how the results are meant to be consumed downstream. An agent has everything needed to call it correctly and act on the results.

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

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

Schema description coverage is 100% and the schema already explains the optional `types` filter with an example and 'Omit for all.' The description's 'types limits the result to some types' adds nothing beyond that, 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 ('Lists every interactive question type Sparka supports') and enumerates what each entry contains (JSON schema, usage guide, example). It also names the sibling that consumes the output (sparka_presentation_save), so an agent can place it in the workflow without opening a schema.

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

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

It clearly establishes the downstream relationship: sparka_presentation_save accepts only these types and fields, which tells an agent to consult this list before authoring a deck. It does not explicitly say when *not* to call it or how it differs from sparka_deck_guide, so it stops short of full when/when-not/alternative coverage.

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

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

Annotations already cover read-only/idempotent/non-destructive semantics, but the description adds behavior annotations cannot express: results for a live presentation are partial, and participant-typed content (nicknames, word-cloud entries) must be treated as untrusted text. The latter is a meaningful prompt-injection caution that changes how an agent treats the payload.

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 return shape, then the input choice, then usage fit, closing with the untrusted-text caveat. Dense but 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?

Rich annotations and an output schema mean the description needn't explain return formatting, and it doesn't overreach — it summarizes content, discloses the partial-results edge case and the input fallback rule, and flags untrusted content. Nothing needed to call 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 description coverage is 0%, so the description must carry the load, and it does: it names both parameters and explains the non-obvious semantics of presentation_id ("its most recent session (the live one if running — results are then partial)"). It doesn't state that exactly one of the two must be supplied, nor the ID prefix formats, which the schema does encode.

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?

Opens with a specific verb and resource ("Returns results for a session") and then enumerates the payload granularity: per-question counts/words, correct answer, correct-count, participant count, final leaderboard. This is far more than a restatement of the name and lets an agent decide on the tool 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?

Explicitly frames when this is the right call: "Suited to follow-ups like summaries, 'who won', or a recap slide", and explains the session_id vs presentation_id choice including that presentation_id resolves to the most recent session. No explicit when-not/negative case or named sibling alternative, 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.