Educaplay

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

Annotations already declare the full behavioral profile (not read-only, idempotent, non-destructive, closed-world), and the description adds nothing beyond the "(tag)" synonym. It does not say what happens when the label already exists (covered only implicitly by idempotentHint) or whether the activity must be owned by the caller.

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

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

A single short sentence with the verb and resource front-loaded and zero filler. Nothing could be removed without losing information.

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

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

For a two-parameter, 100%-documented, non-destructive tool with complete annotations, the description covers the essentials. It is slightly thin in that no output schema exists and the description says nothing about the result of adding a label or duplicate handling, but this is minor for such a simple operation.

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 (label, activity_id) are already fully documented in the schema, including the 127-character limit. The description adds only the parenthetical synonym and no format or constraint 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 ("Add") and resource ("label") and clarifies the synonym "tag", so the agent knows exactly what the tool does. It does not, however, differentiate itself from the sibling remove_label or from update_activity, which also touch activity metadata.

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

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

There is no when-to-use or when-not-to-use guidance. With remove_label sitting in the sibling list, the description could have stated that this adds rather than removes a label, but it leaves that inference entirely to the tool name.

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

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

Annotations only cover the safety profile (write, non-destructive, open-world), so the description must carry the rest, and it does: it discloses append-to-end placement, whole-play behavior, and the shape of the response (title, description, length, start/end seconds). It does not mention permissions, ordering relative to existing timeline content, or failure modes, keeping it below 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, front-loaded with the action and placement, and every clause carries information (append position, playback behavior, URL provenance, return shape). The trailing relative clause about 'at' is slightly tangled but still 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, the description usefully explains what comes back, and it covers placement and URL-sourcing rules. Gaps remain around preconditions (does the quiz need an existing timeline?), whether existing videos are affected, and error behavior, so it is strong but not complete.

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

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

Schema description coverage is 100%, so both url and activity_id are already documented, giving a baseline of 3. The description reinforces url provenance ('only with a link the user gave') and explains that the returned start/end seconds are what each question's 'at' refers to, but adds no syntax or format detail beyond the schema.

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

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

The description gives a specific verb and resource (add a YouTube video) plus placement semantics ('to the end of the timeline of a video quiz, playing whole'), which no sibling tool duplicates. It never names a sibling or contrasts itself against alternatives, so it lands at a clear-but-undifferentiated 4.

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?

'Only with a link the user gave, never an invented one' is an explicit, actionable usage constraint that tells the agent when this tool may be invoked. It stops short of naming alternatives or stating when not to attach a video, so it is clear 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?

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds the concrete consequence: with 'remove' the explanation 'goes away with its image or audio and cannot be undone', while 'remove_text' preserves media. It also discloses the response shape ('lists the items that changed and in "skipped" the ones that could not, with the reason'), which annotations cannot convey.

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

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

Front-loaded with the core purpose and the usage gate, then a dense per-action breakdown plus return-value note — every clause carries information. It is a single heavy sentence-chain with quoted tokens and semicolons, which is slightly harder to scan than a bulleted form would be, but nothing is filler.

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

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

There is no output schema, yet the description still explains the return payload (changed items plus a 'skipped' list with reasons), and it covers the destructive asymmetry between 'remove' and 'remove_text'. For a 4-parameter, 2-enum mutation tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above it by defining each of the four 'action' enum values behaviorally, which the schema leaves as a bare 'What happens to those explanations.' It also clarifies the 'scope'/'items' complementarity, though that is partly redundant with the schema's own 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 set ('Remove explanations, or choose when the player sees them') plus a scope-limiting clause ('without touching anything else'). Names the sibling boundary explicitly ('to take away only the image or audio, use remove_item_media'), so the agent can separate this from remove_item_media, set_item_explanations and set_item_images.

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

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

Gives an explicit gating rule ('Call it ONLY when the user asked for it') and then enumerates when each action applies: 'remove' for full deletion, 'remove_text' for text only, 'show_always' vs 'show_on_mistake' for display timing. It also routes the media-only case to an alternative tool, which is exactly the when-not guidance that prevents misfires.

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 write (readOnlyHint=false), idempotentHint=true and destructiveHint=false, and the description reinforces this with the merge semantics: it only fills empty fields and never overwrites existing values. That merge-only behavior is genuinely useful context beyond the annotation flags, though permissions, error behavior and side effects on the catalog are not discussed.

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 core action, then the trigger, then the exclusion rule. The sentences are long and somewhat run-on (the level/area/labels enumeration inside a conditional), but every clause carries routing 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?

Covers the multi-step workflow dependency, value sources and the no-overwrite constraint for a 4-parameter, nested-schema write tool with no output schema. Only prerequisites such as authentication or required prior state are unstated.

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

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

Schema coverage is 100% and the nested level object is fully documented in the schema itself, so baseline would be 3. The description adds the workflow-level meaning that values should be drawn from next_step.catalog and the content's topic, tying parameters back to the calling context rather than adding per-field syntax.

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

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

States a specific verb (fill in) and resource (the classification of an activity), naming exactly which fields it populates: educational level, knowledge area and labels. This clearly differentiates it from siblings like set_activity_content, add_label and set_activity_audience.

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 the trigger condition (set_activity_content lists "level", "area" or "labels" in next_step.fields) and the value source (next_step.catalog plus the activity topic). It also gives the when-not rule: to change an already-set value, use set_activity_audience, add_label or remove_label instead.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds that the activity is created *empty* (a non-obvious state) and that the response carries the content_schema needed downstream, which is genuine behavioral value. Missing only details like whether creation is idempotent or requires auth.

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 action, then the return value, then the guardrail; every sentence earns its place. Slightly awkward non-native phrasing ('Its result brings "content_schema"') costs a point on polish.

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

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

For a 4-param creation tool with no output schema and full annotation coverage, the description covers state ('empty'), the returned payload, and the workflow constraint. Only minor gaps remain, such as what happens to the previously open activity or whether the new activity needs publishing.

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%, including a long enum explanation with best_for guidance, so the baseline of 3 applies. The description adds no parameter-level meaning of its own beyond referencing the type concept.

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

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

States a specific verb and resource ('Create a new empty activity') plus the scope ('for the current user'), and immediately clarifies the yield ('content_schema') that separates it from set_activity_content and update_activity. An agent can tell this is the entry point of the activity-building flow 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?

Explicit when-not guidance: 'create a second one only when the user explicitly asks for another activity, never as a way around the type that is open.' It also implies the correct next step (set_activity_content) and thus which sibling to use after.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered without the description. The description adds the gating rule about explicit user requests, but says nothing about cost, latency, model behavior, or what a 'description' contains. Adequate but not rich beyond 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?

Three short sentences with zero filler. The core action leads, the input source follows, and the invocation guard comes last, which is the right ordering for an agent scanning top-down.

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

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

For a single-parameter, read-only tool with no output schema, the definition covers action, input provenance, and the trigger condition. The only gap is that the shape of the returned description is not characterized, which is minor given the tool's simplicity and the readOnly annotations.

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 single parameter is documented identically in both places ('Id returned by list_my_media or search_image_library'), so the description adds no meaning beyond the schema. Baseline 3 applies when the schema does the work.

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

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

States a specific verb and resource: 'Describe one image of the media library.' It also names the two sibling tools that produce the required input (list_my_media, search_image_library), which helps an agent locate it among a large sibling set. It stops short of saying how it differs from those siblings beyond input provenance.

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

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

Gives an explicit usage condition: 'Use it only when the user explicitly asks about an image,' plus the prerequisite for obtaining media_id. It does not name what to use instead when the user has not explicitly asked, so the exclusion is stated but the alternative path is left implicit.

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, but the description adds genuinely non-obvious behavior: TTS quota consumption, that pre-existing audio is kept unless existing='replace', and that texts with a video or YouTube link are always left untouched. The keep/replace mechanics are partly restated from the schema enum, which slightly caps this score.

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 single dense paragraph is front-loaded with the most important constraint (only on explicit user request) and every sentence carries distinct information, so nothing is padding. It is, however, a run-on block that would be easier to parse as short bullets given 8 parameters.

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?

Despite having no output schema, the description explains the return value ('generated' lists every text that got audio, with its element and item). Combined with the quota warning, the preservation rules, and the mapping guidance for all 8 parameters, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real interpretation: it maps the user's phrasing onto 'elements' via media_targets.audio ('the questions' = question, 'the answers' = choice, 'everything' = every element), and explains how 'answers', 'positions', 'selection', and 'listed_texts' interact with what the user said.

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+scope: 'Generate the spoken audio of a part of the activity and save it into its texts.' This clearly separates it from siblings like attach_video, illustrate_items, and describe_image, which handle different media types.

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

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

Gives an explicit hard precondition ('Call it ONLY when the user asked for audio in their own words') and an explicit prohibition with rationale ('never add audio on your own initiative, not even to finish an activity you have just written'), because generation spends the user's TTS quota. This is exactly the when/when-not guidance an agent needs to avoid over-calling.

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 read scope (what state is surfaced), which is modest added value, but says nothing about failure behavior for an unknown activity_id or any authorization requirements.

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 the verb and resource first and the return facets listed after the colon; no filler. The list is slightly dense but every element is informative.

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

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

With no output schema, the description usefully enumerates what the read returns, and annotations cover the safety profile, so an agent can call this correctly. The remaining gap is the lack of any error/not-found behavior, which is minor for a single-entity read.

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

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

Only one parameter exists and schema description coverage is 100%, so the schema already documents activity_id fully. The description adds no format, range, or lookup semantics beyond 'one activity'; baseline 3 applies when the schema does the work.

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

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

States a specific verb ('Read') and resource ('one activity') and enumerates the returned facets (metadata, labels, settings, quality suggestions, publish blockers), so the agent knows exactly what this returns. It does not, however, distinguish itself from overlapping siblings like get_activity_content or get_publish_blockers, whose subject matter it explicitly claims to include.

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 gives no when-to-use framing and no alternatives or exclusions, even though get_activity_content and get_publish_blockers cover a subset of what this tool returns. An agent must infer from the name alone which of the three to call.

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. The description adds two behavioral facts beyond that: results are paginated and returned in a readable form. It does not describe ordering, item structure, or what happens at page boundaries.

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 the resource and the two result characteristics front-loaded. No filler, no repetition of the title.

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

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

For a read-only, closed-world tool with fully documented parameters, the essentials are present. With no output schema, the description does carry the burden of describing the return, and 'readable form' is only a gesture at what a content item looks like; nothing tells the agent how to detect the last page or what item types appear.

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 activity_id, page and page_size are already fully documented in the schema. The description's mention of pagination only echoes what page/page_size already say, adding no format or default details. Baseline 3 is appropriate.

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

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

States a specific verb (read) and resource (content items of one activity) plus the shape of the result (paginated, readable). An agent can distinguish this from get_activity (metadata) or get_activity_schema without opening a schema. It stops short of naming 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?

There is no when-to-use or when-not-to-use guidance. The description never mentions get_activity, get_activity_schema, or set_activity_content, so the agent must infer that this is the retrieval counterpart to the content-mutation tools. No prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the return payload (content schema + writing guide + limits), which matters because there is no output schema. It doesn't note whether the response is large or cacheable, but that's a minor gap.

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

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

A single sentence with no filler, front-loaded with the verb and the exact resource, and the destination sibling named at the end where it belongs.

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 does the necessary work of naming the three returned pieces (schema, writing guide, limits), which is enough for an agent to know what it will receive. Slightly short of 5 because 'writing guide and limits' is left unelaborated and the include_settings branch of the output isn't described.

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

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

Schema description coverage is 100% with an enum of 20 activity types, so the schema fully documents both parameters. The description adds only the scoping phrase 'for one activity type' and never mentions include_settings or what the settings catalog contains beyond the schema's own wording. 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?

Specific verb+resource: 'Get the JSON schema of the "content" argument of set_activity_content for one activity type'. It names the exact payload it supplies (schema plus writing guide and limits) and ties itself to the sibling that consumes that payload, which distinguishes it from get_activity, get_activity_content, and list_activity_types.

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 reference to set_activity_content makes the usage context clear: this is the pre-flight lookup for constructing that call's content argument. However, it never states the imperative ('call this before set_activity_content') nor any when-not conditions such as using list_activity_types for enumeration.

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 fully covered without the description. The description adds the useful framing that the result reports 'what is blocking it', but does not disclose the shape of that feedback or any auth/rate considerations.

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

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

A single efficient sentence with the outcome-oriented purpose front-loaded and no filler. It could arguably say slightly more about usage, but nothing is wasted.

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

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

For a simple one-parameter, read-only diagnostic whose annotations cover the safety profile, the description is adequate. No output schema exists, so a hint at the blocker report format would help, but it is not essential to call it correctly.

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

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

With a single parameter at 100% schema description coverage, the schema already documents activity_id. The description adds no format or semantic detail about the parameter, 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 ('check') and resource ('publishing blockers' / whether an activity can be published), so the agent knows this is a diagnostic read. It is reasonably distinguishable from siblings like publish_activity, though it does not name them 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?

Usage is implied - check before publishing - but there is no explicit when-to-use guidance, no statement of prerequisites, and no referral to publish_activity or other siblings. An agent can infer the context but must do the work itself.

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

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

Annotations mark this as destructive and open-world; the description adds real context beyond them: existing images survive unless existing='replace', which discards the old image, texts with a video or YouTube link are always left untouched, and the response reports 'applied' vs 'pending' texts. That is meaningful disclosure of side effects and mutation scope that the annotations alone do not convey.

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

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

Front-loaded with the core purpose and no filler sentences; every clause carries operational information. It is nonetheless a dense single paragraph, and the long enumeration of selection shapes ('the odd or the even items, the first five, one named text...') is illustrative rather than strictly necessary, which keeps it short of a 5.

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

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

No output schema exists, yet the description explains the return shape ('applied' with element, item and image content, plus 'pending'), the 40-entry batching rule with continuation in the same turn, the media_targets.image source of valid element kinds, and the video/YouTube exception. An agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the schema already documents all five parameters and the baseline is 3. The description nevertheless adds disambiguation the schema lacks: 'the questions' maps to element 'question' and never to question+choice, 'the answers' means choice, and 'keep' is the value for every ADD request while 'replace' is reserved for explicit change requests.

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 precise verb and resource (adds images to activity texts by searching the Educaplay image bank and a stock library, choosing the best match and attaching it) and explicitly scopes what it does not touch (text, audio). The phrase 'It is the way to add images' separates it from siblings like search_image_library and set_item_images without the agent needing to open any schema.

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

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

Gives an explicit trigger ('ONLY when the user asked for images in their own words') and an explicit prohibition ('never illustrate an activity on your own initiative, not even one you have just written'). It also routes selection behaviour (send exactly the user's selection, up to 40 entries, call again in the same turn for the rest) and the keep/replace condition, leaving little to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the ordering is non-deterministic ("order changes on every call") and a how_to_choose guidance field is present, which an agent would not learn from the schema or 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 tightly packed sentences with no filler, front-loaded on the verb+resource and what is returned, then usage. Slightly dense (nested clauses in the first sentence) but nothing is wasted.

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

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

With no output schema, the description carries the burden of describing return values and does so (localized name, best-for, payload key, capabilities, how_to_choose). For a one-optional-parameter read-only tool, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100% and the sole optional parameter (only_ai_capable, default true) is fully documented in the schema. The description's phrase "types the assistant can create and edit" loosely corresponds to that filter but adds no syntax or default details beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ("List the activity types the assistant can create and edit") and enumerates the returned fields (localized name, best-for, payload key, capabilities). It is clearly distinguishable from sibling list/get tools such as list_my_activities and get_activity_schema by framing this as the type catalog rather than user content.

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

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

Gives an explicit when-not condition and names the alternative: "Not needed when the user already named the type: create_activity takes it directly." It also implies the positive case (choosing a type for a new activity) via the reference to how_to_choose, so the agent knows both when to call it and when to skip it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety and mutation behavior are covered. The description adds useful context about current-user scope, newest-first ordering, and pagination, but does not describe return shape, total counts, or filter behavior beyond pagination.

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

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

The description is a single front-loaded sentence with no filler. Every clause earns its place by stating resource, scope, ordering, and pagination support.

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

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

For a read-only list tool with five optional filters and no output schema, the description is adequate but incomplete. It omits that the tool supports filtering by activity type, title text, and published state, and it gives no sense of the returned activity representation.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description only explicitly mentions pagination and does not add syntax, defaults, or semantics for type, query, or published beyond what the schema provides.

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: 'List the activities of the current user.' This clearly distinguishes it from siblings like create_activity or get_activity, but it does not explicitly differentiate it from list_my_media or describe how it differs from activity-search-related 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?

The description states scope and ordering but gives no when-to-use guidance, no alternatives, and no exclusions. It does not tell the agent when to use this tool versus get_activity for a single record or how filtering should be approached.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: result ordering (newest first), scope (only media already in activities), and the key limitation that file contents are not describable from this list — which prevents an agent from fabricating descriptions.

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 with no filler; the scope and ordering constraint is front-loaded, and the second sentence is purely the routing rule. Every clause carries information an agent needs.

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

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

With no output schema, the description could be expected to explain the return shape; it does state ordering and, importantly, that the listing carries no content information, which is the main thing an agent would otherwise misinterpret. Pagination details are left to the schema, which is a minor gap for a 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 kind, page, and query are each already documented in the schema, making 3 the correct baseline. The description adds no filtering syntax, default page size, or pagination behavior beyond what the schema states, so it neither compensates nor detracts.

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 (listing the user's existing media files) and immediately scopes it: only files already attached to activities, newest first, with no semantic relation to what they show. It also explicitly separates itself from the sibling search_image_library, so an agent can route correctly without opening either schema.

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

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

Gives a clear selection rule: use this when the user just needs to point at one of their own files, and use search_image_library when the goal is choosing an image for text. That is explicit alternative-routing, though it does not address the other media-adjacent siblings (attach_video, set_item_images, remove_item_media) that could also be confused with it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the safety profile is covered. The description adds real value by disclosing that the tool self-validates and fails with a blocker list rather than silently publishing, but it never says whether publishing is reversible, what state the activity ends in on success, or why the operation is flagged destructive.

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 no filler: the purpose and outcome come first, then the failure behavior. Nothing is repeated from the title or schema, and every clause is load-bearing.

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

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

For a one-parameter, no-output-schema tool with full annotation coverage, the description supplies both the success intent and the failure mode, which is close to sufficient. It stops short of covering reversibility or post-publish visibility, the two facts most likely to affect an agent's decision.

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

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

There is a single parameter with 100% schema description coverage, so the schema fully documents activity_id. The description adds no format, sourcing, or constraint detail beyond it, which is the expected baseline for a well-covered schema.

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

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

Specific verb (publish) plus resource (activity) and the observable outcome (playable and shared), so an agent can distinguish it from unpublish_activity and update_activity. It does not explicitly name the closely related sibling get_publish_blockers, which is the main thing an agent would weigh it against.

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

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

Usage context is implied rather than stated: you call this when you want an activity to become playable/shared. There is no explicit 'use X instead when Y' guidance, even though get_publish_blockers and unpublish_activity are obvious alternatives in the 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 declare destructiveHint=true, so the description's 'It cannot be undone' reinforces rather than reveals. However, it goes beyond the annotations by disclosing the response shape ('removed' vs 'skipped') despite there being no output schema, plus the 40-per-call limit — genuinely valuable behavioral context for a destructive operation.

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 and irreversibility, then usage rules, then result format — a sensible order. It is dense and slightly clause-heavy, and the swap example is verbose, but essentially every sentence carries routing or behavioral information.

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

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

For a destructive mutation tool with no output schema, the description covers irreversibility, the exact user-intent conditions, the excluded alternative, the item cap, and the return structure. Missing only explicit permission/authorization requirements, which keeps it short of 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?

With 100% schema description coverage, the schema already documents kind, items, text, in_item and activity_id thoroughly. The description's 'send exactly the texts the user named, up to 40 per call' maps onto the items array and its maxItems, and adds only the 'only named texts' intent, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource — removing the image or audio from named texts — and scopes it with 'leaving the text and everything else as it is.' It actively distinguishes itself from siblings by naming illustrate_items, set_item_images and generate_field_audio, so an agent can route correctly without inspecting schemas.

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

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

It gives an explicit trigger ('Call it ONLY when the user asked to remove, delete or take away...'), covers the medium-swap case with a described two-step workflow, and states a hard exclusion ('Never use it to change an image for another image... that is existing: replace in ...'). Alternatives and the condition that selects them are both spelled out.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=false, so the safety profile is covered. The description adds only the identifier semantics ('by its name') and says nothing about what happens when the label does not exist or whether an error or a no-op is returned.

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 short sentence, front-loaded with the verb and resource, with zero wasted words. Nothing is redundant or 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 simple two-parameter mutation with rich annotations, no output schema and full schema coverage, the description covers what is needed. It could go slightly further by noting behavior for a missing label, but the essentials are present.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema ('Name of the label to remove', 'Id of the activity'). The description's 'by its name' reinforces but does not extend 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+resource ('Remove a label (tag) from an activity') and clarifies the synonym 'tag', so an agent knows exactly what the tool acts on. It does not explicitly distinguish itself from the inverse sibling add_label, but the verb makes the direction unambiguous.

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

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

There is no when-to-use or when-not-to-use guidance, and no mention of the related add_label alternative or any prerequisite for having the label exist first. 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, destructiveHint=false, idempotentHint), so the bar is lower. The description still adds real behavioral context beyond them: no activity side effects, candidate sources (Educaplay bank + stock library), and the divergent return behavior of a single-query vs multi-query call.

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

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

It is dense but front-loaded: the non-mutating distinction and the sibling routing come first, then batching rules, then the downstream tool. Every sentence carries information, though the clause chain is long enough that a shorter phrasing was possible.

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: it describes candidate shape ('source' and a descriptive 'title'), the differing result size for single vs multi queries, and where the returned ids go (set_item_images). Nothing an agent needs to call or 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%, so baseline would be 3, but the description adds meaning the schema lacks: 'one query per concept, up to 10' clarifies the intent of the array, and it explains that page is only relevant for a single-query call, which the schema does not state.

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

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

The description states a specific verb+resource ('List image candidates') and immediately scopes it ('WITHOUT adding anything to the activity'), which cleanly separates it from the mutating sibling illustrate_items. An agent can pick the right tool without opening either schema.

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

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

It gives explicit when-to-use ('only when the user asks to see or to choose among options') with quoted trigger phrases, and names the alternative (illustrate_items) plus the condition that selects it ('to put images on the activity'). Both branches are unambiguous.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=false, so the agent knows this is a mutating but repeatable call. The description adds the scope restriction, but does not disclose what actually gets overwritten (e.g. that area=0 clears an existing knowledge area, or that changing lang relabels the activity). Adequate, not rich.

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

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

Two sentences, zero filler, with the purpose front-loaded and the usage restriction immediately after. 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 four-parameter mutation tool with full schema coverage, no output schema, and annotations carrying the safety profile, the description covers purpose and when-to-use adequately. The only real gap is behavioral: it does not warn that the call overwrites or clears existing audience/language/area values.

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

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

Schema description coverage is 100%, so the schema already documents activity_id, area, lang and the nested audience object in detail. The description only paraphrases the same three concepts at a higher level, adding no syntax, format or constraint beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Set) and resource (activity audience) and enumerates the three dimensions it controls: content language, target audience, knowledge area. This clearly separates it from nearby mutators like set_activity_content or set_activity_privacy, though it never names 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?

Gives an explicit when-not condition: 'Call it only when the user asks for one of these; a title or a description never needs it.' That is real routing guidance. It stops short of naming the alternative tool an agent should use instead for content or metadata edits.

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 openWorldHint=false, so the safety profile is covered. The description adds the genuinely useful behavioral constraint that content must conform to a type-specific schema sourced from create_activity or get_activity_schema, which is not derivable from the structured fields.

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

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

Two sentences, tightly front-loaded: the action first, then the critical schema-source guidance. 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?

For a mutation tool with a nested object parameter, the description covers the key pitfall (unsourced content schema) and annotations handle safety and openness. Return behavior is not described, but no output schema exists and the call itself is fully specified; a quick note on append-vs-replace consequences would complete it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for the nested 'content' property by telling the agent where to obtain its required schema. The mode enum semantics are left to the schema, which already documents them.

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 pair ('Add or replace') and the exact resource ('the content of an activity'), making it immediately distinguishable from the read counterpart get_activity_content. An agent can tell what this does without opening anything else.

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 strong prerequisite guidance: the content object must follow the activity type schema obtained from create_activity's content_schema or get_activity_schema, with the emphatic 'Never guess it.' However, it does not contrast with update_activity or clarify when to prefer append vs replace beyond the schema enum.

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, readOnlyHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds the scope of the change (visibility plus hidden Top 10 ranking), which is useful, but says nothing about reversibility, permission requirements, or how the change interacts with other privacy settings.

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 scope of the change front-loaded ahead of the invocation condition. 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 small three-parameter mutation tool with full schema coverage and annotations carrying the safety profile, the description covers what the tool changes and when to call it. It is not missing anything an agent strictly needs, though a note on the effect of the change (e.g., whether it is reversible or immediate) would round it out.

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

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

Schema description coverage is 100%, so the enum values and hide_results semantics are already fully documented in the schema. The description restates the two mutable dimensions at a high level but adds no syntax or constraint detail beyond what the schema provides, which is the expected baseline.

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

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

The description states a specific verb and resource ('Change who can reach the activity: its visibility and whether the Top 10 ranking of scores is hidden'), which is clear on its own. However, it does not distinguish itself from the close sibling set_activity_audience, which likely also governs who can reach an activity, leaving the boundary ambiguous.

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

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

It gives an explicit invocation constraint: 'Call it only when the user asks to change one of the two.' That is clear contextual guidance on when to call. It stops short of naming the alternative tool or when NOT to use it relative to set_activity_audience or update_activity_settings.

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

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

Goes well beyond the annotations by disclosing that existing explanations are overwritten ('replaced' when one already existed), that everything else is preserved, the 40-item batch cap, and partial-failure semantics via 'skipped' with reasons. It stops short of saying whether an overwritten explanation is recoverable or what permission/state (e.g. published vs draft) the write requires.

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 purpose, then usage exclusions, then limits, then return shape — every clause carries real routing information. It loses a point for dense nested negatives ('Asking when explanations are shown...is not asking to write them') that take effort to parse.

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 compensates by explaining the result contract: 'written' for items that got an explanation, 'replaced' for ones that already had one, and 'skipped' with reasons. Combined with the batch limit and the do-not-fill policy, an agent has everything needed to call this correctly and interpret the response.

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 'item' (verbatim text identifying the item in get_activity_content) and 'explanation' (one or two informative sentences, never just "Correct!") are already documented. The description only restates the 40-item cap that maxItems already encodes, adding no new meaning beyond the schema. Baseline 3 is correct here.

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 object ('Write or rewrite the explanation of items that already exist') and immediately bounds the scope by naming what is left untouched (texts, images, audio, explanation media). An agent can distinguish it from set_activity_content and change_item_explanations 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 an explicit trigger ('ONLY when the user asked to add, write or change explanations...they name, or of all of them'), explicit negatives ('never set_activity_content "replace" for that', 'never rewrite an existing explanation' when only display timing is asked, 'never fill the items that have none, offer it instead'), and names the correct alternative (change_item_explanations). This is about as complete as when-to-use guidance gets.

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 openWorldHint=true, but the description adds real context: it does not touch text or audio, a text with a video/youtube link is always left untouched, and the prior image is discarded only under 'replace'. It also discloses the shape of the result. Slightly overlaps with the enum description in the schema, but the mutation semantics are genuinely clarified.

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

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

Front-loaded with the core action and the guardrail on when to use it, then moves to targets, semantics, and result. It is dense and mostly earns its length, though a few clauses (e.g., the target-type enumeration) could be trimmed without loss.

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 the result reports, covers edge cases (existing images, video/youtube texts), target eligibility, and correct input sourcing. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further: it explains which element types are valid targets ('media_targets.image'), that 'text' must be copied verbatim from get_activity_content, and that you send the choice to illustrate a choice and the question to illustrate a question. This meaningfully disambiguates 'text' and 'in_item' beyond the schema text.

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

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

States a precise verb and resource ('Put one specific image, chosen by its id, on texts of the activity') and immediately scopes it against siblings like illustrate_items and search_image_library. An agent can distinguish it from the auto-finding 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?

Explicit routing rules: use only when the image was user-pointed (from list_my_media or a chosen search_image_library candidate), use illustrate_items when the user just wants images found for them, and 'Call it ONLY when the user asked for images in their own words.' Names both the alternative and the selecting condition.

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 (readOnly=false, idempotent=true, destructive=true), the description discloses that hiding is reversible (text stays stored and can be shown again), that image and audio are never touched, the prerequisite that a text must already have an image, the dependency on media_targets.image_only in the activity state, the 40-per-call limit, and the return shape (hidden/shown/skipped with reason). This is unusually rich behavioral context; the only mild tension is with destructiveHint=true, though that is a defensible annotation of a player-visible content change rather than a contradiction.

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 core action is front-loaded and every sentence earns its place, but it is delivered as one long dense paragraph mixing usage gating, prerequisites, limits and result format; light structural separation would improve scanability without cutting content.

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 3-parameter mutation tool with no output schema, the description covers the prerequisites, the per-type constraint source (media_targets.image_only), the batch limit, and the return fields (hidden/shown/skipped with reason), leaving no significant gap an agent would need to guess at.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: items should contain exactly the texts the user named, capped at 40 per call (matching maxItems), and a text can only be hidden if it already has an image, which constrains what is valid input. It does not elaborate on the in_item disambiguator, which the schema already covers.

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

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

The description names the specific action (hide a text so only its image shows, or show it again) and the resource (item texts within an activity), which cleanly separates it from siblings like set_item_images, illustrate_items, and remove_item_media.

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?

Explicit when-to-use is given with verbatim user phrasings ("leave only the flag", "put the names back") plus a call-it-ONLY gating condition, and an alternative workflow is spelled out: if the user wants images-only on texts that have none, call illustrate_items first, then this tool in the same turn.

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 this as a destructive, open-world write, but the description adds real substance: replacement discards the old picture, a "search" replacement always yields a different picture, and the result reports what the picture shows plus the piece count. It never contradicts the annotations. It stops short of stating reversibility or failure modes for a missing attachment/image_id.

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

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

The purpose and the puzzle-only constraint are front-loaded, and each subsequent sentence covers a distinct source or the keep/replace rule. The prose is dense and quote-heavy, but no sentence is redundant with another.

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

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

There is no output schema, yet the description says what the result reports (what the picture shows, piece count), which is exactly what an agent needs to chain calls. Combined with the source routing rules and the puzzle-state precondition, nothing essential is missing for a 6-parameter mutation.

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 enums and all six parameters are already documented; the description largely restates the schema's own wording for "source" and "existing" ("Only the field of that source is used" appears in both). It does add one cross-field fact not in the schema — that a "search" replacement is always a different picture — which lifts it slightly above the baseline.

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

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

The description opens with a concrete verb and resource ("Put the picture of a puzzle") and immediately scopes it to the assembled image rather than question/answer images. It explicitly routes the sibling case to illustrate_items, so an agent can separate this tool from set_item_images and illustrate_items 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 states the precondition ("Only for a puzzle (its state has 'puzzle')"), names the alternative for the excluded case (illustrate_items), and explains which source to pick for each situation. The "keep" vs "replace" guidance even quotes the user phrasings that justify replacement, leaving nothing to infer.

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, and the description usefully qualifies that: the activity 'stays editable and can be published again,' so the agent knows this is a reversible state change rather than data loss. It still omits side effects on live learners/audience settings, so it adds real but incomplete context.

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

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

Two short sentences, effect front-loaded, with the reversibility note second. Nothing is padded or redundant.

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

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

For a single-parameter mutation with no output schema and annotations covering the safety profile, the description gives the essential state-transition semantics. Minor gaps remain around prerequisites and whether audience/privacy state is preserved.

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

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

Only one parameter and schema coverage is 100%, so the schema fully documents activity_id. The description adds no format, range, or sourcing detail beyond it — the baseline 3 applies when the schema does all the work.

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

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

States a specific verb (unpublish) and resource (activity) plus the concrete effect: the activity can no longer be played. That is enough to separate it from publish_activity, though it never names the sibling or contrast 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?

Usage is implied by the effect statement — take an activity offline without deleting it — but there is no explicit when-to-use, no prerequisites (e.g. whether the activity must currently be published), and no named alternatives such as update_activity for pure edits.

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=false? No -- they declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the safety profile is partly covered. The description adds real behavior beyond that: partial updates are supported (omit the field you don't want to touch) and both fields are required before publishing, with set_activity_content reporting empties. It doesn't explain what 'destructive' means here (overwriting an existing title) or permission requirements, so it's not complete.

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

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

Three short sentences, zero filler, with the core action ('send only what you want to change') and the publish precondition front-loaded. Every sentence carries distinct information rather than repeating the name or 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 4-parameter mutation tool with no output schema, the description covers the partial-update contract, the publish precondition, and sibling boundaries, which is most of what an agent needs. It leaves the destructive/idempotent implications of overwriting an existing value and any authorization requirement unstated, so it is strong but not exhaustive.

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%, including a detailed intent enum explaining fill_empty vs user_asked, so the schema carries nearly all parameter meaning. The description's 'send only the one you want to change' restates optionality already implied by the schema and adds little syntax or format detail. 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 and resource ('Update the title and the description of an activity') and immediately scopes it away from related siblings ('The audience and the visibility have their own tools'), which separates it from set_activity_audience and set_activity_privacy in the sibling list. An agent can identify 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?

Gives concrete usage context: 'Send only the one you want to change,' plus the precondition that both fields are needed for publishing and that set_activity_content surfaces missing values in next_step. It routes audience/visibility work to other tools. It stops short of an explicit when-not rule (e.g., when to prefer set_activity_content over this tool), so it's clear context without full exclusions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered by structured data. The description adds the scope of mutable settings, but does not clarify the surprising destructiveHint=true implication — whether unspecified settings are preserved or reset — which is exactly the behavior an agent needs to know before calling.

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 no filler, and the mutation scope is front-loaded ahead of the discovery instruction. 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 two-parameter, fully-described schema with annotations carrying the safety profile and no output schema, the description covers what changes and how to find valid fields. The remaining gap is the partial-versus-full update semantics implied by destructiveHint=true.

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

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

Schema coverage is 100% so the two parameters are documented, but the settings object's schema description is generic ("Object with setting fields and their new values"). The description adds real value by pointing to get_activity_schema(include_settings: true) as the authoritative source for valid setting keys, going beyond what the nested schema conveys.

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

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

The description names a specific verb and resource ("Update game settings of an activity") and gives concrete examples of the affected fields (time limit, attempts, shuffling), which distinguishes it from the broader update_activity sibling. It stops short of explicitly contrasting itself with update_activity, but the scope is unambiguous.

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

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

It gives an actionable prerequisite: call get_activity_schema(include_settings: true) to discover the editable fields before invoking this tool. That meaningfully routes the agent, though it offers no when-not guidance or explicit alternative for cases where the update should happen elsewhere.

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