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

With no annotations provided, the description carries the behavioral disclosure burden. It explicitly discloses the non-obvious side effect of creating a flashcards section if the site lacks one, and it explains the SM-2 spaced-repetition review behavior. It does not mention permissions or idempotency, but the main side effects are usefully surfaced.

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 three short sentences, front-loaded with the main purpose. Every sentence adds meaningful context: the action, the section-creation side effect, and the review behavior. There is no redundant or filler 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?

Given the nested deck parameter, optional section_id, and the nearby add_flashcards sibling, the description is too sparse for reliable invocation. An agent can understand the tool's high-level purpose but cannot confidently determine how slug, section_id, and deck fields should be supplied. The output schema may help with return shape but does not resolve these parameter-level gaps.

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

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

Schema description coverage is only 33%, and the description does not compensate: it never explains slug, section_id, or how the deck object should be structured. The schema's deck description lists fields, but slug and section_id semantics are completely opaque. This leaves significant ambiguity for invoking the tool correctly.

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 clearly states the resource and action: 'Add a new flashcard deck to a site.' It also adds a useful non-obvious detail about creating a flashcards section if none exists. It does not explicitly contrast with the sibling tool add_flashcards, though the deck-versus-cards distinction is inferable.

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: an agent should use this when adding a deck to a site. However, there is no explicit guidance about when to prefer this over add_flashcards or how it relates to removing or updating decks. The only contextual hint is the auto-creation of a flashcards section.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully states that the operation is an append, so existing cards are not replaced, and it notes Markdown support. However, it does not mention response behavior, error cases, permissions, or duplicate handling, leaving some gaps.

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 two short sentences with no filler. The core action is front-loaded, and the Markdown note is a valuable addition that 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?

The tool is relatively simple and an output schema exists, so return-value documentation is less critical. Still, with no annotations and a low-parameter-description coverage, the description leaves out important context about what 'slug' and 'deck_id' refer to and does not fully specify the expected card object shape.

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 low at 33%, and the description only adds meaning to the 'front' and 'back' fields of the cards parameter via the Markdown note. The required 'slug' and 'deck_id' parameters are left unexplained, and the description does not compensate for the poorly specified cards schema.

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

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

The description states a specific verb ('Append') and a clear resource ('cards to an existing deck'), making the action unambiguous. It also distinguishes itself from the sibling 'add_flashcard_deck' by explicitly targeting an existing deck rather than creating one.

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

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

The phrase 'existing deck' clearly communicates that this tool is for adding to an already-created deck, which implies the prior use of a deck-creation tool. It does not name alternatives or state explicit exclusions, but the usage context is clear.

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?

No annotations are provided, so the description must disclose behavior itself. It adds context about target URL forms and the numbering aspect, but does not state whether the tool appends or inserts, whether an existing path is required, authorization needs, side effects, or what happens with position=null. This is a significant transparency gap for a write 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?

The description is two short sentences, front-loads the core purpose, and the target-type note is directly useful. There is no redundant or vague wording.

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?

The tool has three parameters, including a nested step object and an optional position, plus no annotations and low schema coverage. The description clarifies only target and never explains slug, position semantics, or how a step is ordered, even though an output schema exists to cover return 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?

The only parameter-level value added is the clarification that target may be a section id, page filename, anchor, or full URL. The required slug and optional position are left undocumented in both the schema and description, and schema coverage is only 33%, so the description does not compensate enough for the remaining parameters.

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 action ('Add a numbered step') and a precise resource ('the learning path on the landing page'). The verb and object clearly distinguish it from broad path operations like set_learning_path, and no misleading filler is present.

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

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

The description implies the tool is for adding a step to the landing-page learning path, but it never states when to prefer this over set_learning_path or any other sibling. There are no explicit alternatives, exclusions, or preconditions, so the guidance is left to inference.

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

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

With no annotations, the description carries the behavioral burden and does it well: it discloses merge semantics, YouTube embed behavior, and the visual distinction for source="internal". It stops short of 5 because it does not cover authorization, idempotency, or error behavior.

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

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

The description is compact, front-loaded with the purpose, and every sentence contributes a distinct behavioral detail: purpose, merging, embedding, and internal-link marking. There is 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?

An output schema exists, reducing the need to describe return values, and the core behavior is covered. However, the description still lacks meaning for required slug and optional kind/section_id, and it never routes between this and sibling content-add tools, so an agent must infer several details.

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 only 20%, so the description must compensate. It adds useful semantics for group_label and items, but required slug is left undefined and section_id/kind are unexplained, leaving key parameters under-specified.

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 specific verb and resource: 'Add prerequisite resources' and enumerates the content types (YouTube videos, blog posts, courses, docs). This distinguishes the tool from sibling add-* tools such as add_flashcards and add_section.

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 resource-type list implies when the tool should be used, but there is no explicit statement of when not to use it or which sibling tool to prefer for adjacent cases. An agent can infer basic usage, but exclusions and alternatives are left unstated.

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?

With no annotations, the description carries the behavioral burden. It provides meaningful behavior beyond the obvious add action: creating a new page and rendering unknown types as generic custom sections from blocks. It does not cover error behavior or reversibility, but the disclosed behaviors are genuinely useful.

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 two focused sentences with no filler. The core action is front-loaded, and the second sentence adds a high-value extensibility detail without rambling.

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

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

Given the presence of an output schema and the nested 'section' parameter pointing to get_payload_schema, the description covers the main action and the most important behavioral nuance. It could be more explicit about how slug identifies the target site, but the overall context is sufficient for an agent to proceed.

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

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

The input schema already documents the section object and position, but slug has no description and the schema coverage is only 67%. The description adds semantic value by explaining how 'type' and 'blocks' interact for custom sections, but it does not fully compensate for the undocumented slug parameter or the open-ended section object.

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

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

The description states the specific action ('Add a section to a site') and a notable outcome ('creating its own page'). This clearly separates it from sibling tools like update_section, remove_section, and reorder_sections.

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

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

The description implies the create use case and even mentions an advanced scenario (adding unknown content types), but it never explicitly contrasts this tool with alternatives such as update_section or remove_section. Usage context is present but the when-not-to-use guidance is left to inference.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It does so by clearly stating that the site and everything under it will be deleted, making the destructive scope obvious. It stops short of mentioning irreversibility or required permissions, but for a deletion tool this is strong transparency.

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

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

The description is a single sentence with no filler. It front-loads the action, identifies the target resource, and adds the critical scope detail without waste.

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 delete operation, the description covers the most important contextual fact: deletion cascades to everything under the site. An output schema exists, so explaining return values is unnecessary. Minor gaps are irreversibility and explicit confirmation behavior, but the description is sufficient for correct invocation.

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

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

Schema description coverage is 0% and the description does not mention the slug parameter at all. The parameter name 'slug' offers minimal inferable meaning, but the description fails to define what a slug is, its format, or how it identifies the target site.

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 uses a specific action verb, 'Delete', with a clear resource, 'a rendered site and everything under it.' This distinguishes it from sibling tools like get_site, render_site, and remove_section by making the destructive, site-wide scope explicit.

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

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

The phrase 'and everything under it' implies this is for full-site deletion rather than targeted removal, which is relevant compared to siblings like remove_section. However, it does not explicitly state when to use this tool versus alternatives or mention prerequisites such as the site needing to already exist.

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?

With no annotations provided, the description carries the behavioral burden. It discloses two important non-obvious behaviors: unknown keys are preserved and shown on the page, and unknown section types degrade to a generic custom section instead of failing. This adds real value beyond the tool's basic purpose, though it does not discuss authentication or output format, which are at least partially covered by the output schema.

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 short and front-loaded with the core purpose. Each sentence adds relevant information: the return value, the usage timing, and the permissiveness behavior. No filler or redundancy is present.

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 tool with one optional parameter and an output schema, the description covers everything essential to invoke it correctly: what it returns, when to call it, and the permissive schema behavior that affects downstream rendering. The output schema handles return structure details, so the description does not need to repeat them.

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

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

Schema description coverage is 0%, and the description does not mention the include_example parameter at all. While the parameter name and title are self-explanatory to a human, the description provides no explicit link between the worked example mentioned and this boolean flag. The description should clarify that include_example controls whether the worked example is returned.

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

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

The description states a specific action: 'Return the JSON Schema for a site payload, plus a worked example.' This clearly identifies what the tool does and its output. It also distinguishes the tool from render_site by positioning it as a prerequisite step.

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 explicitly says 'Call this before render_site the first time,' giving agents a direct trigger condition for use. This is clear, actionable guidance that also implicitly tells the agent not to call render_site blindly before retrieving the schema.

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?

With no annotations, the description carries the full burden of behavioral disclosure. 'Inspect' and 'get' imply a read-only operation, which is helpful. The description also reveals the payload behavior (default vs. full stored JSON). It does not mention error handling, prerequisites, or explicit side-effect absence, but the read-only implication is fairly strong.

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 two short sentences with no fluff. The primary purpose is front-loaded, followed by the optional payload enhancement. Every sentence earns its place, and the structure supports quick scanning by an agent.

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

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

Given this is a simple read tool with an output schema and only two parameters, the description covers the essential behavior and the key parameter option. A minor gap is the relationship to render_site (whether a site must be rendered first), which could confuse an agent, but overall the description is sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description must explain the parameters. It clearly explains include_payload ('get the full stored JSON back'). The required slug parameter is not described, though its meaning is reasonably inferable from the tool name and context. The description adds value for one parameter but leaves the other undocumented.

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 specific verb and resource: 'Inspect a rendered site' and lists its parts (sections, decks, learning path). This clearly distinguishes the tool from siblings like list_sites (listing) and render_site (rendering) without needing to open schemas. It is immediately obvious what get_site does.

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

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

The description implies usage for inspecting an existing rendered site and offers a concrete use case for include_payload ('useful when you want to reason about existing content before patching it'). However, it does not explicitly contrast with any sibling tools or state when not to use this tool, leaving some selection reasoning to the agent.

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?

No annotations are provided, so the description must carry the behavioral transparency burden. It states scope and output ('with its URL') but does not explicitly declare read-only behavior, lack of side effects, or any prerequisites. For a simple listing tool, this is minimally adequate but not richly transparent.

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, direct, front-loaded sentence with no filler. Every word contributes meaning.

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

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

For a zero-parameter list tool with an output schema, the description is nearly complete: it names the action, scope, and included data. The only minor gap is the lack of explicit routing against siblings, but this is not essential for correct invocation.

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

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

The input schema has zero parameters, so there is nothing for the description to explain. The 0-parameter baseline of 4 applies.

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

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

The description uses a specific verb 'List' and resource 'sites', with clear scope: 'every site rendered on this machine' and output detail 'with its URL'. This clearly differentiates it from sibling tools like get_site (single site), render_site, or delete_site.

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: use this tool when you need an overview of all sites or their URLs. However, there is no explicit guidance about when not to use it or when to prefer alternatives like get_site for a specific site.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It exposes the destructive nature of the operation ('Delete') but does not mention irreversibility, whether associated flashcards are also deleted, or any side effects on the site.

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, well-front-loaded sentence with no filler. Every word contributes to the core meaning.

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?

The description is too minimal for a destructive tool with no annotations. It omits parameter semantics and behavioral side effects, so an agent cannot fully determine how to call the tool safely or what consequences to expect.

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

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

Schema description coverage is 0%, and the description does not explain the two required parameters, slug and deck_id. It only hints at a site/deck relationship, leaving the agent to infer that slug identifies the site and deck_id identifies the deck.

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 ('Delete'), a specific resource ('flashcard deck'), and a scope ('from a site'). It clearly distinguishes this tool from siblings like add_flashcard_deck and delete_site.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of related operations like adding a deck or listing sites. The description only states what the tool does, not the conditions under which it should be chosen.

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?

With no annotations, the description carries the burden of disclosing behavior. It explicitly states that the section is removed and its page is deleted, which reveals a destructive side-effect. However, it does not mention irreversibility, required permissions, or any additional cascading effects beyond the page deletion.

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, efficient sentence with no wasted words. It front-loads the primary action and immediately communicates the important destructive effect.

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?

Although the tool has only two parameters and an output schema exists, the description is too sparse for safe invocation. It lacks parameter semantics, usage guidance, and sufficient behavioral context for a destructive operation. The agent would have to infer the roles of slug and section_id without explicit support.

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

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

The input schema has 0% description coverage, and the description does not explain how 'slug' and 'section_id' are used. It only says 'remove a section,' which maps weakly to section_id, but leaves slug completely unexplained. The description adds no meaningful parameter information beyond the schema's property names.

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 clearly identifies the action ('Remove a section') and its direct consequence ('delete its page'). It distinguishes this from sibling tools like add_section, update_section, and delete_site by specifying a distinct removal operation on a section and its associated page.

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

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

There is no guidance about when to use this tool versus alternatives, no prerequisites, and no mention of when not to use it. The only implied context is that this tool removes a section, but the description does not explicitly route the agent toward it or away from similar tools like delete_site.

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?

With no annotations, the description carries the behavioral disclosure burden. It does disclose the full-site rendering behavior, URL return, and the one-shot vs. patch lifecycle. However, it omits the destructive overwrite behavior implied by the overwrite parameter, which defaults to true and replaces an existing site with the same slug; that detail is only present in the schema.

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, purposeful sentences front-load the core action and outcome, then provide essential lifecycle guidance. There is no filler, repetition, or unnecessary detail.

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 complex tool with a large nested SitePayload schema, the description gives the key selection and lifecycle context an agent needs: call once per site, then patch afterward. It is slightly incomplete because it does not directly explain that re-rendering with the same slug can overwrite an existing site, but the schema's overwrite parameter description covers that.

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 payload and overwrite parameters are already well documented in the schema. The description adds only "full site" framing, which reinforces the payload meaning but does not materially extend 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?

Opens with a specific verb, resource, and outcome: "Render a full site and return its URL." This clearly distinguishes render_site from sibling add_* and update_* tools, which patch stored payloads incrementally rather than rendering a complete site.

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

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

"Use this once per site" is an explicit when-to-use instruction, and the description directly names the alternatives: "prefer the add_* and update_* tools." It even explains why they are preferred, eliminating ambiguity about later 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?

With no annotations, the description bears the full burden of behavioral disclosure. It clearly explains an important non-obvious behavior: omitted section IDs are not deleted or lost, but retain their relative order at the end. This goes beyond the basic 'reorder' statement and helps the agent predict the outcome.

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 convey both the primary action and the key behavior. There is no filler, and the most important information is front-loaded. Every sentence 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 tool with an output schema, the description covers the core behavioral nuance. It lacks explicit guidance on what slug refers to and does not discuss edge cases like duplicate or unknown section IDs, but these are not critical for basic correct usage.

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

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

Schema description coverage is 0%, so the description must compensate. It adds crucial meaning to section_ids by explaining partial reordering semantics. Slug is not explicitly described, though its role as an identifier is reasonably inferable from the name and context.

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 the exact action and resource: 'Reorder sections.' It also communicates the unique partial-reorder semantics, which distinguishes this tool from siblings like add_section, update_section, and remove_section. An agent can immediately tell what this tool is for.

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 intended use is implied by the name and first sentence, but there is no explicit guidance about when to choose reorder_sections over update_section or other section-related tools. It explains how the operation behaves, but not the conditions that make it the right tool.

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

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

With no annotations, the description carries the full burden. 'Replace the whole learning path' clearly indicates a destructive overwrite of the existing path, which is a critical behavioral trait. It tells the agent what gets destroyed (the previous path), though it omits additional details like reversibility or side effects.

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 wasted words. It is efficient and easy to parse, though it is arguably too sparse to be fully useful.

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?

The description is too minimal for a tool with two required parameters, no annotations, and no parameter explanations. It lacks usage context, parameter semantics, and any detail about return values or behavior in edge cases, leaving the agent to infer too much.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not explain slug or steps. It only hints that steps are what the path is being replaced with, leaving the semantic meaning of both parameters largely undefined.

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 'Replace the whole learning path.' states a specific action (replace) and a resource (learning path). The word 'whole' suggests it overwrites the entire path, distinguishing it from sibling add_learning_path_step, though it does not explicitly name alternatives.

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

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

No guidance is provided on when to use this tool versus alternatives like add_learning_path_step or update_section. There are no exclusions, prerequisites, or context clues beyond the bare action statement.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Change' and does not disclose whether the theme is fully replaced or merged, whether unspecified properties are preserved, whether changes persist, or what side effects occur for an invalid slug or theme.

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, direct sentence with no filler or repetition. The action and target are front-loaded, making it easy for an agent to process quickly.

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?

The output schema means return values need not be described, and the theme schema provides a concrete example. Still, the description omits important invocation context such as whether the provided theme replaces existing settings or merges with them, and there are no annotations to cover mutation caveats.

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

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

The description maps the theme object to understandable concepts: 'accent colours' covers accent/accent_soft and 'default light/dark mode' covers dark_default. However, it does not explain the slug parameter, and with only 50% schema description coverage, it only partially compensates for the schema's gaps.

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

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

The description states a specific action ('Change') and a precise resource: the site's accent colours and default light/dark mode. This distinguishes it from the sibling site tools such as get_site, render_site, delete_site, and update_meta, leaving no ambiguity about what set_theme does.

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 intended use is implied by the wording: use this when you need to change theme-related appearance settings. However, there is no explicit statement about when not to use it or which alternative tool (e.g., update_meta) should be chosen for other site metadata changes.

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?

No annotations are present, so the description must carry the full behavioral burden. It lists updatable fields but does not state whether existing values are merged or overwritten, whether the operation is reversible, whether all listed fields are required in patch_fields, or what happens to unspecified fields. This is a significant transparency gap for a mutation tool.

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

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

The description is a single, focused sentence with no filler. The action and target fields are front-loaded, making it easy to scan and understand.

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 a simple two-parameter shape, the description lacks behavioral details (merge vs. replace, field requirements), usage guidance, and any definition of slug. With zero annotations, an agent would still have to infer critical invocation semantics.

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

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

The description adds meaning for patch_fields by naming the hero fields, and the schema already lists them in the patch_fields description. However, slug is undocumented in both the schema and the description, and patch_fields value types, optionality, and behavior with additionalProperties are not clarified. With 50% schema coverage, the description partially compensates but does not fully define the parameters.

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

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

The description states a specific action ('Update the hero') and enumerates the target fields (title, subtitle, summary, repo links, setup command), which distinguishes it from sibling update tools like update_section or set_theme. However, the resource 'hero' is somewhat terse and doesn't clarify which site it applies to.

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

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

No guidance is given on when to use this tool versus alternatives such as update_section, set_theme, or other site-management siblings. There are no exclusions, conditions, or context triggers, only a statement of what the tool does.

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?

No annotations are provided, so the description carries the behavioral burden. It discloses shallow-merge semantics and the important trait that whole list fields are replaced rather than appended, which is non-obvious and critical. It does not cover all potential side effects, but it highlights the most safety-relevant behavior.

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

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

The description is two tight sentences with the key behavioral caveat front-loaded after the core definition. Every sentence adds value, and there is no redundant wording.

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

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

Given that an output schema exists and the three parameters are minimal, the description covers the most essential operational detail: shallow merge with list replacement. It does not explain selection semantics of slug/section_id in depth, but those are reasonably inferable from their names and the 'existing section' framing.

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 only 33%, with patch_fields documented in the schema. The tool description adds meaning to patch_fields by explaining shallow merge and list replacement, but slug and section_id remain undocumented beyond their names, leaving a moderate gap.

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

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

States a specific operation ('shallow-merge fields') on a specific resource ('an existing section'). It also distinguishes itself from sibling tools by explicitly redirecting list-additions to add_flashcards or add_resources.

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

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

Clearly implies use for patching existing sections and explicitly warns against using it for appending lists, naming alternatives. It lacks a fuller when-to-use/not-use distinction with other update-like siblings, but the critical routing guidance is present.

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