Voice School Lesson Booking

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

With no annotations provided, the description carries the full burden of disclosing behavior. It explains the creation of a lead, the requirement of at least one contact method, and explicitly limits its scope by stating it cannot confirm lessons or create schedule items. This is meaningful context that goes beyond the basic 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 two concise sentences, front-loaded with the primary purpose. The second sentence adds a requirement and an exclusion, both earning their place without redundancy or fluff.

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 13 parameters and an output schema, the description provides essential context about the tool's purpose and constraints. It does not explain return values (covered by output schema) or every parameter, but it offers enough for an agent to understand the action and its limitations. Sibling tool differentiation could be stronger, but the description is self-sufficient for most cases.

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 the key constraint that 'requires name and at least one contact method,' which clarifies the relationship between the name and contact fields. However, it does not describe the other 12 parameters, relying on the schema's titles and defaults, so it only partially compensates.

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 action: 'Create a request-first lead for an online vocal lesson.' It distinguishes this from siblings by explicitly noting it never confirms a lesson or creates a schedule item, which sets it apart from tools like search_lesson_availability or list_lesson_options.

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 provides clear context for when to use this tool: when you need to initiate a request-first lead. It also includes an explicit exclusion ('never confirms a lesson or creates a private schedule item'), which helps avoid misuse. However, it does not directly name alternative tools or provide explicit when-not-to-use guidance beyond this exclusion.

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 carries the full disclosure burden. It usefully discloses the token requirement and the dual create/update semantics, but it does not mention that the publish parameter can take a draft live, nor how an update overwrites existing content — both consequential behaviors 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?

Two sentences, each earning its place: the first summarizes purpose and content shape, and the second states the authentication requirement. It is dense but not bloated, and the purpose is front-loaded.

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 21-parameter creation tool with zero annotations and zero schema descriptions, this description is incomplete. The update-vs-create trigger, the redundancy of channel_title/channel_url alongside channel_slug, and the publish flag's side effects are all left to inference. The output schema mitigates only return-value questions, not 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?

Schema description coverage is 0%, so the description must compensate, but it names only the headline content fields (SEO title, keywords, tags, source URL, text/video blocks). The six required parameters (coach_slug, channel_slug, channel_title, channel_url, source_post_url, write_token) and the remaining optional fields such as slug, excerpt, language_code, and source_platform are left unexplained in both schema and description.

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

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

The description states a clear verb+resource ('Create or update a trainer social post') and enumerates the content payload (SEO title, description, keywords, tags, source URL, ordered text/video blocks). The name 'draft' plus the sibling publish_social_post imply a drafting stage, but the description does not explicitly differentiate itself from 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 gives no guidance on when to use this tool versus siblings such as publish_social_post, upsert_social_channel, or list_social_posts. The only prerequisite mentioned is the write token, so an agent gets no selection cues and no exclusions.

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

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

No annotations are provided, so the description carries the full burden. It adds useful behavioral context by stating 'active' (filtering only active services) and 'live' (real-time database source). However, it does not disclose the read-only nature, potential side effects, or any limitations such as pagination or required permissions, which would be expected given the absence of annotations.

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

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

The description is a single, well-structured sentence that front-loads the main action and resource. Every word adds value, and there is no redundant or filler content. It is appropriately sized for the tool's simplicity.

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 simple and has an output schema, so the description does not need to explain return values. It clearly states the purpose, target coach, and data source, making it mostly complete. However, the lack of parameter explanation and explicit usage guidance relative to siblings slightly reduces completeness, though the output schema compensates for return-value 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?

The schema has 2 parameters with 0% description coverage, and the description does not compensate. It mentions 'for a coach' which loosely maps to coach_slug, but it completely ignores the language parameter. There is no explanation of parameter formats, defaults, or how they affect the output, leaving the agent with insufficient information.

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 identifies the resource ('active lesson services and prices for a coach') plus the source ('live Voice School database'). This clearly distinguishes it from sibling tools like create_lesson_request (creation), search_lesson_availability (availability search), and voice_school_info (general school info).

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 provides clear context for when to use this tool: to retrieve active lesson services and prices for a specific coach. It does not explicitly mention alternatives or exclusions, but the sibling tool names make the distinctions obvious, so the context is sufficient without overt when-not-to-use 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?

With no annotations, the description carries the transparency burden. It communicates a read-only list of published posts and the URL fields returned, but it does not disclose pagination, ordering, scope (e.g., current trainer vs any trainer), or any auth/permission 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 sentence with no filler; the key verb, resource, status filter, and return detail are all front-loaded.

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 exists, so return-shape concerns are reduced, and the description covers the main purpose. However, it is incomplete for a five-parameter tool: an agent cannot tell from the description which optional filters are available or how they behave.

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 for the five undocumented parameters. It does not explain limit, language, platform, coach_slug, or channel_slug, nor their defaults or filtering behavior.

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 ('published trainer social posts') and adds output detail (canonical and original source URLs). This clearly distinguishes it from sibling tools like create_social_post_draft, publish_social_post, or list_lesson_options.

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: retrieve published trainer social posts. The word 'published' hints at when it applies, but the description gives no explicit guidance about when to choose this over alternatives or when not to use it, such as when drafts should go to create_social_post_draft.

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 and does so well: original file retained privately, validated MP3 prepared, only the selected part converted, title/description/order/author/URLs/other parts/publication flags preserved, and 'Never publishes.' It also discloses idempotency semantics for request_id (identical retry reuses arguments and ID; changed arguments conflict).

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

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

Dense but front-loaded, leading with the scope constraint before inputs and return shape. Every sentence adds distinct information, though the semicolon-heavy run-ons pack several concepts into single sentences.

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

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

For a 7-parameter mutation tool with no annotations and no output schema, the description covers access rules, prerequisites, input format, side effects, return contents (fresh revision, part_id, media with web URL, MIME, duration), and idempotency. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate. It explains filename and base64_data (accepted formats OGG/Opus, MP3, WAV, M4A, AAC, FLAC; max 100MiB/10min) and the uniqueness/idempotency contract for request_id. It leaves token, article_id, part_id and revision largely to inference, though it points at online_article_get for revision/part_id.

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

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

States a specific verb and resource: 'Set audio on a selected TEXT/AUDIO part of an own inactive unpublished draft.' It also scopes the operation (own, inactive, unpublished) which clearly separates it from online_article_update, online_article_publish and online_media_prepare.

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 prerequisite ('Read online_article_get for current revision and part_id') and states the access restriction (staff and foreign correction grants denied). It names a sibling for input sourcing but stops short of an explicit 'use X instead when...' exclusion for the sibling tools.

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

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

With no annotations, the description carries the full burden and does well: it discloses the auth model (Coach-Token owner only, staff credentials denied), the default state (private inactive draft), the publish/is_active invariant, and the slug-conflict failure mode. It does not cover validation-failure behavior, idempotency, or rate limits, so it stops short of exhaustive.

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 auth constraint, then progressively details payload shape and edge cases; almost every clause carries information. It is dense and run-on in places (bullets would aid scanning), but not 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 tool with a complex open nested payload, no annotations, and no output schema, the description covers auth, defaults, invariants, error handling, and even summarizes the return (ID, revision, publication flags, URLs). Minor ambiguity remains around several optional payload fields and failure semantics, but nothing critical to a correct call is missing.

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

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

Schema coverage is 0% and payload is an open nested object, so the description must compensate — and it does, enumerating slug, title/description/slugs/cover_alt ru/en maps, parts structure, tags, localized covers, and the AUDIO-specific fields (file_name, file_base64, optional description/order). The token parameter itself is only implied via 'active Coach-Token owner' rather than directly documented.

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

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

States a specific verb+resource ('Create a material') and immediately scopes the caller ('as the active Coach-Token owner only'). It is clearly distinguishable from siblings like online_article_update, online_article_publish, and online_article_audio_set, which are named or implied by context.

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/when-not routing: creation with a required stable slug here, but 'To attach validated MP3 audio to an existing own draft part use online_article_audio_set.' It also states the publish precondition ('Set publish:true only after approval') and the slug-conflict protocol ('list/get before retry; never duplicate').

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 and does disclose the authorization model (ownership/operator grant, denial of other IDs) and that authorship, media, URLs and publication state are read-only. It omits error/denial behavior and any rate or token constraints, so it is strong but 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?

Two sentences, purpose front-loaded, with no filler. The opening clause is dense and slightly awkward ('an owned or explicitly operator-granted selected material'), but it earns its place by packing scope, access model and returned fields together.

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 and no annotations, so the description must do everything; it does describe returned content and read-only fields, which covers the main gaps. It falls short on the token parameter and on failure/denial behavior, so it is adequate but not fully complete for a two-required-parameter 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 coverage is 0% and neither parameter has a description. The phrase 'by ID' loosely maps to article_id, but the required 'token' parameter is entirely unexplained in both schema and description, leaving half the inputs 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?

States a specific verb (Read) and resource (material by ID) plus the payload it returns (revision and plain text of existing parts), which is enough to distinguish it from online_articles_list and online_article_update. However, it never names or contrasts those siblings explicitly, and the term 'selected material' is looser than 'article'.

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

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

It gives an access precondition ('owned or explicitly operator-granted') and an exclusion ('Other IDs are denied'), which is real usage context. But it never says when to prefer this over online_articles_list (to find an ID) or online_content_get, so the routing guidance is only implied.

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

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

With no annotations, the description must carry the full behavioral burden. It discloses the key effect ('Makes the article active with a publication timestamp, immediately public') and permission model ('owned by this active Coach-Token's original author'), but omits whether publication is reversible, what errors occur on unauthorized attempts, and how to correct wording afterward. These are significant gaps for a mutation tool with no annotation coverage.

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

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

Four front-loaded sentences with no filler. The ownership requirement, prerequisite read, publication effect, and final warning are ordered logically. Slight redundancy between 'Read online_article_get first' and 'Confirm final wording before calling' keeps it from being maximally tight.

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

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

For a no-annotation, no-output-schema publish mutation, the description covers the essential invocation path: ownership requirement, prior read, revision source, and public effect. It remains incomplete on post-publication behavior, reversibility, and failure modes, which an agent might need for safe 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 is the only source of parameter meaning. It usefully clarifies that token must belong to the active Coach-Token's original author, that article_id must refer to an existing owned material, and that revision must be the current revision from online_article_get. However, it does not explain revision format, token acquisition, or article_id scope beyond ownership, leaving gaps for all three undocumented 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 verb and resource ('Publish an existing material') and immediately distinguishes the action from sibling reads by directing the agent to online_article_get first. It also clarifies the scope ('existing material') versus creating a new article, making the tool's purpose unmistakable.

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 prerequisites ('Read online_article_get first and supply its current revision'), a clear when-not condition ('foreign correction grants and staff credentials never authorize publication'), and a procedural warning ('Confirm final wording before calling'). An agent knows exactly when and how to invoke it relative to other article tools.

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

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

With no annotations provided, the description carries the behavioral burden and discloses important traits: access is limited to the active Coach-Token owner and explicitly granted materials, drafts and current revisions are included, and staff/global site access is excluded. It also describes how returned text should be treated. It omits pagination and return-format details, though an output schema exists.

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

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

The description is front-loaded with the core listing behavior and then adds access exclusions and data-handling guidance. It is appropriately sized, though the first sentence is dense and could be slightly clearer.

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 covers the tool's access scope and content inclusion well, and the output schema removes the need to explain return values. However, it leaves the required token parameter unexplained and does not help the agent choose this tool over nearby siblings, so it is only adequately complete.

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

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

The schema has zero description coverage for the single required 'token' parameter, and the description never explicitly explains the token's format or role. 'Coach-Token owner' gives weak contextual inference, but the parameter itself remains largely 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 states a specific verb ('List') and resource ('materials'), and clarifies the access scope: active Coach-Token owner plus exact operator-granted materials, including drafts and revisions. It distinguishes the access boundary with 'No staff or global site access,' though it does not explicitly route the agent against sibling tools such as online_article_get.

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

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

The description does not say when to use this tool versus alternatives like online_article_get or online_content_get. It provides an access constraint ('No staff or global site access') and notes that returned text should be treated as editorial source data, but this is not the same as explicit usage 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?

With no annotations, the description carries the full burden and does well: it discloses that corrections become public immediately, that original author/slugs/media/tags/state are preserved, that 'new' is escaped plain text, and that each 'old' must match exactly one text-node occurrence. It omits revertibility and rate-limit/permission-failure behavior, keeping it from 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?

The description is dense but front-loaded, leading with scope and the read-first requirement before detailing payload syntax. Every sentence carries an operational constraint, though the format examples make it somewhat heavy 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?

For a 4-required-param mutation tool with 0% schema coverage, no annotations, and no output schema, the description covers scope, prerequisites, payload format, preservation semantics, and publication effects. Only the token/auth parameter and any return behavior go unaddressed.

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

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

Schema coverage is 0%, so the description must compensate, and it does for the tricky 'changes' payload by giving concrete shapes (plain title/description, parts array, replacements) and explaining that 'revision' comes from get. 'token' and 'article_id' are left unexplained, which is the main residual 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?

The description opens with a specific verb+resource ('Correct ... articles') and bounds the scope with 'owned/operator-granted' and 'no global pages', which meaningfully separates it from a general content-editing tool. It does not explicitly name how it differs from siblings like online_content_edit, so it falls short of a 5.

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

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

It states a clear prerequisite workflow ('read revision, html and text_nodes first') and a caution ('confirm wording before calling') tied to the immediate-publication behavior. It does not name an alternative tool or a when-not-to-use condition, so it stops short of explicit 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?

With no annotations, the description must carry the full behavioral burden; it does disclose that this is a read, that it requires staff read permission and view_association, and that it returns the current revision. It says nothing about behavior on a missing/non-positive ID, or what happens with stale revisions, which are the main uncertainties for a read-by-ID 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?

Two short sentences, zero filler, with the read operation and its selector front-loaded before the permission requirements. Every clause carries 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 read tool with no output schema, the description covers purpose, key selector constraint, and authorization needs. Only return shape and failure behavior are unaddressed, which is a minor gap at this complexity.

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 supply the meaning. It does add real semantics for association_id ('positive ID'), constraining it beyond the bare integer type, but 'token' is never explained and error behavior for invalid IDs is unspecified.

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 ('Read one DB association') plus the selector ('by positive ID') and the returned state ('with current revision'). It implicitly separates itself from online_associations_list (plural) and online_association_upsert, though it never names an alternative 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?

'Staff read and actual view_association required' gives the caller's preconditions for use, which is clear context an agent can act on. It stops short of naming when to prefer online_associations_list or online_association_upsert instead, so no explicit exclusion is provided.

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 and largely meets it: it discloses an immediate, externally visible side effect ('immediately public'), the permission scope required, the optimistic-concurrency requirement on revision, and hard content limits (256KiB, passive shapes only, banned constructs). It does not say what is returned or whether a failed revision leaves the prior logo intact.

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?

Five tight clauses with zero filler, and the two highest-stakes facts (public immediately, revision required) come first. The telegraphic register occasionally costs readability ('Staff save/change_association') but nothing is wasted.

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

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

For a 4-parameter mutation with no annotations and no output schema, the description covers side effects, authorization, concurrency and payload validity. The remaining gap is the return value and stale-revision error behavior, which nothing else in the structured data supplies.

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

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

Schema coverage is 0%, so the description must compensate, and it does for the highest-risk parameter: svg is defined as raw UTF-8, capped at 256KiB, and restricted to passive shapes with a list of disallowed constructs, plus the explicit exclusion of URLs and filenames. token and association_id are only implied through 'Staff ... and current revision' and the tool name, so some gap remains.

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 ('Save logo') plus the storage model ('local random SVG file') and a consequence ('immediately public'). It is distinguishable from online_association_upsert and online_association_get by scope, though it never names a sibling 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?

'Staff save/change_association and current revision required' gives a real precondition, which is more than most. However there is no explicit statement of when to prefer this over online_association_upsert, nor any when-not guidance or mention of what happens on a stale revision.

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 burden and discloses important behavior: maximum 200 results, inclusion of bilingual fields/revisions, required private staff read grant plus view_association, and denial of teacher tokens. It stops short of discussing pagination or whether results are sorted, but the access and scope behavior is well covered.

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 and front-loaded: the core list behavior and cap come first, followed by access constraints. Every clause adds useful information without repetition.

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

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

For a one-parameter list tool with an output schema, the description covers the key context: scope cap, returned content nature, and authorization restrictions. The main remaining gap is token parameter format, but the output schema and existing access notes make the definition largely complete.

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

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

The schema has one required token parameter with 0% description coverage, so the description should compensate. It adds authorization constraints tied to the token, including private staff grant and view_association requirements and teacher-token denial, but it does not explain token format or exactly how the token is supplied.

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

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

The description gives a clear verb and resource: list DB associations, with a concrete cap of 200 and the nature of returned fields/revisions. It is distinguishable from the singular get and upsert siblings by being a list operation, though it does not explicitly name those 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?

It specifies access prerequisites and clearly says teacher tokens are denied, which is useful usage context. However, it does not explicitly say when to use this list tool versus online_association_get or other association-related siblings.

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 and does substantial work: it discloses that the write is immediately public, that a staff save grant plus add/change_association permission is required, that revision is an optimistic-concurrency control, and that no membership/certification inference happens. It omits what the call returns, but that is a minor gap for a save 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?

It is short and the purpose is front-loaded, but the telegraphic fragments ('Staff save grant plus add/change_association', 'payload exactly name:{ru,en}…') read as compressed notes rather than prose and take a second pass to parse. No sentence is wasted, yet readability suffers for the density.

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 with a nested free-form payload, no annotations, and no output schema, the description supplies the payload contract, the revision semantics, and the permission gate — enough to call it correctly. Return-value behavior is the only unaddressed piece.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it specifies the exact payload shape (name:{ru,en}, description:{ru,en}, official_url:HTTPS) and the create-vs-update protocol for association_id and revision. Only the token parameter is left unexplained, which is the one meaningful omission.

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 — creating or updating a public DB association — and adds the distinguishing detail that it goes live immediately. It does not name the sibling it supersedes (online_association_get / online_associations_list are obvious complements, but the agent must infer that from the name.

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

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

It gives real branching guidance: association_id null plus empty revision means create; an existing record requires the current revision. It also flags the staff save grant prerequisite and 'confirm wording first'. What it lacks is an explicit statement of when NOT to use this versus other write paths.

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 does carry useful behavioral load: it discloses the required permission grants and notes results come with a 'current revision'. It does not describe behavior for a coach with no memberships, error cases, or whether results are paginated, which leaves real gaps for a tool with zero annotation coverage.

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

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

Two tight sentences with the resource stated first and the permission precondition second; no filler. 'with current revision' is dense but borders on cryptic, keeping 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 and no annotations, so the description is the only source of behavioral detail. It covers auth requirements and revision currency, but omits return shape and empty-result handling, leaving meaningful gaps for an agent that must 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 description coverage is 0% – neither 'token' nor 'coach_id' is documented in the schema. The description only implicitly identifies coach_id as the coach to read for; it says nothing about token (auth credential) or identifier format, so it fails to compensate for the coverage gap.

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

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

States a specific verb (Read) and resource (one coach's DB association memberships), scoped to a single coach rather than a list. An agent can infer this is the read counterpart to online_coach_associations_set, though that sibling is not named explicitly and 'DB association memberships' is slightly jargon-heavy.

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 a precondition ('Private staff read grant and view_coachassociation required') but never says when to choose this over online_associations_list or online_teacher_profiles_get, nor explicitly that online_coach_associations_set is the write alternative. Usage is inferable from the read/set naming pair rather than stated.

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

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

With no annotations, the description carries the full burden and does disclose key traits: it is a destructive replace (empty list removes memberships), it requires a current revision from get (concurrency control), and it explicitly excludes biography/external platform profiles. The 'immediately publicly' wording is unclear about visibility/latency, holding it below 5.

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

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

Front-loaded and reasonably short, but the 'Staff save and actual add/change/delete/view_coachassociation required' segment is malformed and wastes space, and 'immediately publicly' adds ambiguity rather than value.

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 mutation with no annotations and no output schema, it covers the important parts (replace semantics, revision prerequisite, confirm step, memberships shape) but leaves token and coach_id undescribed and the overall phrasing partially garbled.

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

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

Schema coverage is 0%, so the description must compensate. It usefully specifies the memberships structure ({association_id: existing positive integer, member_profile_url: HTTPS or empty}) and the max-40/distinct constraints, but says nothing about token or coach_id, and only hints at revision via the get reference.

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: replace one existing coach's memberships, distinguishing it from the get sibling by the 'ONLY one existing coach' scope. The phrase 'immediately publicly' is confusing but the core operation is identifiable.

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

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

Provides real routing guidance: 'Current revision from get mandatory' points to the get sibling as a prerequisite, and 'Confirm first' flags the confirmation step. The 'Staff save and actual add/change/delete/view_coachassociation required' clause is garbled but signals permission requirements.

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 and does disclose some behavior: shared admin validation (FAQ/effectiveness, bilingual references), permission enforcement, optimistic concurrency via expected_version, and the note that review/offer touches real business records rather than fake ratings. However it omits reversibility of rollback, side effects, and response shape, leaving notable gaps 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 purpose is front-loaded in the first clause, but the rest is semicolon-dense and jargony ('FAQ/effectiveness', 'bilingual references'), mixing purpose, operations, constraints, and workflow into a single crowded block.

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 multi-operation mutation tool with no annotations, no output schema, and 0% schema coverage, the description covers operations, validation, permissions, and concurrency, but leaves the token/data/document parameters and return behavior unexplained, so it is adequate but incomplete.

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

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

Schema coverage is 0% (6 params), so the description must compensate. It adds meaning for operation (the five values), expected_version (concurrency), and request_id, but says nothing about token, data, or document, so it only partially compensates for the coverage gap.

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

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

The description states a specific verb+resource ('Save complete edited draft or publish/rollback its saved revision') and enumerates the operations (save/publish/rollback/review/offer). It is clearly the mutation counterpart to siblings like online_content_get/preview, though the multi-operation scope makes the single stated purpose slightly diffuse.

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?

'Read state first' implies a prerequisite (fetching state via online_content_get/preview) and 'use expected_version and request_id' gives workflow guidance, but no alternative tool is named and no when-not-to-use condition is given. Usage is implied rather than explicit.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavioral context: the state is 'private,' and access 'Requires a bounded administrative MCP credential or existing Coach-Token linked to staff with actual model permissions.' That access-control detail is genuinely useful, though it doesn't state pagination, failure modes, or scope limits of the 'complete' read.

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

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

Front-loaded with the verb, but the middle sentence is a long comma-spliced field enumeration that mixes resource names with implementation-level details (URL/alt/width/height). It is informative but dense and could be tightened.

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 returned editorial state contains, and it covers the auth prerequisite, which is essential for calling a private read. It is largely complete for its complexity, missing only scope/pagination and error behavior.

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

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

There is one parameter (token) at 0% schema description coverage, so the description must compensate. It partially does by characterizing the credential type ('bounded administrative MCP credential or existing Coach-Token linked to staff'), but gives no format, prefix, or acquisition details for the token value itself.

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 ('complete private editorial state') and enumerates the fields returned (RU/EN pages, hero_image, seo-summary, public_summaries overrides, courses, relations, geography, review metadata). It is clear what the tool does, but it never names or contrasts with siblings like online_article_get or online_content_preview, so the agent must infer the split.

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 guidance and no comparison against close siblings such as online_article_get or online_content_preview. The only conditional information is an authentication requirement, not a routing rule between tools.

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

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

With no annotations, the description carries the full burden and does real work: it discloses the authorization requirement (staff permissions), the non-mutating scope ('No publishing'), and a negative guarantee that private storage URLs are not exposed. What remains unstated is whether the preview has any side effects and what shape the previewed content takes.

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 primary mode leads, the alternative follows, and the permissions/safety constraints close it out. Every clause carries distinct 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 4-parameter preview tool with no output schema and no annotations, the description covers purpose, mode selection, authorization, and safety. It is slightly incomplete in not describing what the preview returns or clarifying that only one mode should be used at a time.

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 supply meaning, and it does: it ties page_id+language together as one mode and public_path as an alternative mode, which the bare schema cannot convey. The required 'token' parameter and the silent defaults (page_id='HOME', language='ru', public_path='') are never explained, leaving a gap.

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

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

States a specific verb (preview) and two concrete resources/modes: saved draft context keyed by page_id/language, and a saved public_summaries override keyed by public_path. It is clearly a non-mutating read of saved content, which distinguishes it in spirit from online_content_edit/online_article_update, though it never names those siblings explicitly and the jargon ('draft context', 'public_summaries override') is left undefined.

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 explicit selection logic between the tool's two modes (use page_id/language, or alternatively pass public_path) and states the staff-permission prerequisite. It stops short of telling the agent when to prefer this over online_content_get or online_article_get, so sibling routing is still 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 full burden and does it well: it discloses the authorization requirement (administrative preview token), the safe read-only nature ("Never publishes or changes state"), the important side-effect caveat that inactive articles stay hidden publicly until the original author publishes them, and the exact return content. It even clarifies this is preview context, not a live public webpage, which preempts a plausible misinterpretation.

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

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

Dense but front-loaded – the core action and its scope come first, followed by return contents, then caveats. Every sentence adds information (auth, return fields, hiding behavior, no-state-change), with only mild redundancy between "Context only, not a public webpage" and "Never publishes or changes state."

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

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

With no output schema and no annotations, the description usefully enumerates the return payload (shared version, draft_revision, localized title/description/canonical URL, article titles/URLs/flags), which is exactly what an agent needs. The remaining gap is the undefined `slug` parameter and any error/authorization-failure behavior.

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

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

Schema coverage is 0% across three required parameters with no titles or descriptions, so the description must compensate. It partially does: "in ru or en" effectively constrains `language`, and "administrative preview authorization" explains what `token` is for. However `slug` is never defined (no format, no indication of which section is identified), so a third of the parameters remain opaque.

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

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

States a specific verb and resource ("Preview one privately saved materials section") plus the supported languages (ru/en), so the action is unambiguous. It functionally separates itself from the save/publish siblings by declaring it never publishes or changes state, though it never names an alternative tool explicitly, which keeps it just short of a 5.

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

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

Usage is only implied: the word "privately saved" and "administrative preview authorization" signal this is for inspecting a draft section rather than reading public content. There is no explicit when-to-use statement, no when-not-to-use, and no pointer to the sibling tools (save/publish/get) that would be the alternatives, leaving the agent to infer the routing.

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 and does so well: it discloses a separate administrative publish authorization requirement, DB-lock revision/membership checks, preservation guarantees (other tags/relations, article text/authorship/URLs/publication state), and idempotency semantics (identical retries reuse arguments, changed arguments conflict, ambiguous pending writes fail closed). It even names the return payload.

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

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

Front-loaded with the core purpose, and virtually every sentence carries distinct operational information (prerequisites, preservation, retry behavior). The sentences are dense run-ons that pack multiple clauses, which slightly hurts scanability but wastes little.

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 mutation with no annotations and no output schema, the description covers authorization, locking, preservation, idempotency, and return shape. Remaining gaps are minor: how to obtain the administrative token and concrete examples of expected_version/draft_revision 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 coverage is 0% and all five params are undocumented in the schema, so the description must compensate. It gives partial semantics for four of them (fresh expected_version, exact saved draft_revision, new unique request_id, slug) but never explains token, nor the format/origin of draft_revision or expected_version.

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 with precise scope: 'Publish ONLY one saved materials section and its selected article memberships.' The 'ONLY one saved materials section' framing cleanly distinguishes it from siblings like online_article_publish and online_content_edit without the agent needing to open 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 prerequisite workflow ('Read/get and preview RU/EN first') and an explicit exclusion ('Never activates/publishes an article or other online-page drafts'). It stops short of naming the sibling tools (online_material_section_preview, online_material_section_save) it should be paired with, so routing is inferred rather than stated.

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

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

With no annotations, the description carries the full burden and excels: it states draft-only scope, separate administrative save authorization, what is not changed, the return values, idempotency rules for identical retries, conflict behavior for changed arguments, and reconciliation for ambiguous pending operations.

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 dense but front-loads the core action and prerequisites, and every sentence contributes a constraint or behavioral rule. It is appropriately sized for a complex save tool, though some clauses are packed and could be split for readability.

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 no annotations, no output schema, six required parameters, and a nested payload, the description covers most critical context: authorization, draft-only scope, preconditions, parameter constraints, return values, and retry semantics. The undocumented token parameter is the main missing piece.

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

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

Schema coverage is 0%, so the description must compensate; it thoroughly documents slug, expected_version, section_revision, request_id, and the nested payload shape with constraints. The required token parameter is never mentioned, leaving a notable 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?

The description states a specific verb and resource: 'Save DRAFT ONLY a materials section' and explicitly differentiates from publishing ('Does not ... publish other content'), making it clear this is a draft save, not a publish or get operation.

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 preconditions ('Read online_material_sections_get first') and distinguishes new vs existing section via section_revision, plus explicit exclusions ('Does not create/change a public tag, change any article, or publish other content'). It stops short of naming online_material_section_publish as the alternative when publishing is intended.

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 behavioral burden and does so well: it discloses authentication requirements, denial for teacher credentials, exact read scope, inclusion of private saved drafts and shared content version, and explicit exclusions around private article bodies and publishing.

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 dense but front-loaded, leading with the core read operation and returned data before the permission requirements and exclusions. It avoids filler, though the long first sentence could be easier to scan.

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 or annotation coverage, so the description must supply scope, return contents, auth constraints, and exclusions. It does all of that, including the sensitive draft/version behavior and the read-only boundary against private bodies and 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 0% for the single token parameter. The description adds meaningful auth context by saying the token must be a separate administrative credential with read grant/material permission, but it does not clarify token format, source, or other parameter-level details.

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 and resource: reading existing materials catalog sections (native MaterialTag records). It enumerates the returned fields and scope, clearly distinguishing this read operation from sibling preview, save, and publish tools.

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

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

It gives clear usage conditions: a separate administrative credential with existing read grant/material permission is required, and teacher credentials are denied. It also states what the tool does not do (read private article bodies, publish), though it does not explicitly name sibling alternatives such as online_material_section_preview.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses limits (100MiB/10min), accepted audio formats, that the private original is preserved, the returned MP3 URL/MIME/duration/poster_url behavior, visual media output retention, that no publication occurs, and the prerequisite that FFmpeg must already be installed.

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 dense but mostly front-loaded: purpose, limits, formats, outputs, exclusions, and prerequisite each earn their place. It is appropriately sized for the amount of behavioral detail required, though the run-on paragraph could benefit from clearer structural separation.

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 no output schema and 0% parameter description coverage, the description does well by explaining return values, constraints, preservation behavior, and the FFmpeg prerequisite. It is only incomplete regarding the token and filename parameters, which are required but never 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 0% for all three required parameters. The description adds meaningful semantics for the media data (base64-supplied, format list, size/duration limits), but it does not explain the required token or filename parameters at all. This leaves two of three parameters undocumented in both schema and description.

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

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

The description opens with a specific verb and resource: preparing authorized base64-supplied visual or audio media using ffprobe/ffmpeg. It distinguishes the tool from sibling publishing and fetching operations by stating 'No arbitrary path/URL fetch, no publication.' An agent can identify its scope without opening the schema.

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

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

The description gives clear context and two exclusions ('No arbitrary path/URL fetch, no publication'), which helps rule out inappropriate uses. However, it does not name when to choose this tool over siblings like online_content_edit or online_article_publish, nor does it provide explicit routing alternatives. Usage is implied rather than fully guided.

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 usefully discloses that access requires administrative read authorization, that ordinary teacher tokens are denied, and that returned badge HTML is untrusted editorial data. It also indicates a read-only operation via 'Read', though it does not cover pagination, error behavior, or exact response structure.

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 tightly packed sentences with the core purpose front-loaded and no wasted wording. Each sentence adds distinct value: purpose, authorization constraint, and a data-trust warning.

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 read tool with no output schema and no annotations, the description gives the important context: what is returned, who can access it, and that embedded HTML is untrusted. Minor gaps remain around exact response shape and parameter details, but the critical operational caveats 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 0%, so the description must compensate. It indirectly clarifies that coach_id refers to an existing coach and that token must be an administrative read token, but it does not explicitly define either parameter's format or constraints.

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 read verb and identifies the exact resource: one existing coach's ordered external-platform profile lists, including version, draft, and published lists. This distinguishes it clearly from the sibling write operation online_teacher_profiles_set and from broader content-read tools.

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

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

The intended use is implied by 'Read one existing coach's...' and the administrative authorization note, but there is no explicit when-to-use guidance or comparison to alternatives such as online_teacher_profiles_set. An agent can infer the use case but must still reason about when this tool is preferred.

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 and does well: it discloses draft-only behavior, the admin authorization prerequisite, that other content is preserved, and extensive content-safety constraints (no scripts/iframes/fetching, sanitized attributes, element allowlist). It stops short of explaining concurrency/idempotency semantics of expected_version/request_id or the return shape.

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

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

Front-loaded with the critical constraint (DRAFT ONLY) followed by requirements and then the profile grammar. Extremely dense with every clause carrying information, though the long single paragraph of content rules verges on a wall of text.

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

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

For a mutation tool with no annotations and no output schema, the description is unusually complete, covering safety, authorization, draft scope, and nested field rules. It falls short only on return-value expectations and the token/coach_id parameters.

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

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

Schema coverage is 0%, so the description must compensate, and it does for the most complex parameter: profiles is described in detail (max 20, ordered, platform_url, label, active, button_html vs profile_url/logo_url). It acknowledges expected_version and request_id as required but leaves token and coach_id (beyond 'one existing coach') unexplained.

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 (save) and resource (external profiles for one existing coach) and explicitly scopes it to DRAFT ONLY, which separates it from the publish path. It is clearly distinguishable from the sibling online_teacher_profiles_get and the online_content_edit publication tool.

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

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

Explicitly routes publication to online_content_edit publish/rollback, telling the agent when to use a different tool. It also states the prerequisite of existing administrative save authorization, though it does not explicitly contrast with online_teacher_profiles_get for reading.

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 available, the description carries the disclosure burden and covers meaningful behavioral ground: it requires an auth token and performs source URL validation before publishing. It does not detail side effects such as visibility or irreversibility, but the disclosed auth and sequencing exceed a bare action statement.

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

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

Two sentences, no wasted words, and the key action plus required condition are front-loaded. Every sentence adds 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 simple 2-parameter tool with an output schema, the description is close to sufficient, but the undefined slug and lack of failure behavior/error cases make it only minimally viable for a correct call.

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

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

Schema coverage is 0%, so the description must explain the parameters. It correctly maps write_token to SOCIAL_POSTS_MCP_WRITE_TOKEN, but leaves slug undefined; the agent has to guess what value identifies the prepared post. This is a clear 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?

The description states a specific action ('Publish') on a specific resource ('prepared trainer social post') and adds a validation step. The word 'prepared' clearly separates it from sibling create_social_post_draft.

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 clear context: use this to publish a post that has already been prepared and after source URL validation. It does not explicitly name alternatives or state when not to use the tool, but the context is sufficient to route an agent correctly.

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 transparency burden. It discloses a key privacy trait ('never includes private learner data') and the calculation basis ('working windows and busy intervals'), but omits authentication, rate-limiting, or failure behaviors.

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 sentences, with the primary purpose stated first and a secondary privacy note second. Every sentence adds value and there is no redundancy.

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

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

With an output schema present, return values are covered, but the tool's core operation and parameter interplay remain underspecified. The description is adequate for a high-level gist but lacks enough context for an agent to confidently invoke it with correct parameters, especially with sibling tools 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 0%, yet the description offers no explanation of any parameters, such as coach_slug, date_from/to, or user_timezone. It does not compensate for the missing schema descriptions, leaving parameter semantics entirely to the schema's structural details.

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 tool's function: finding free requestable lesson times using coach working windows and busy intervals. It goes beyond a tautology but does not explicitly differentiate from sibling 'list_lesson_options', which may offer similar capabilities.

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 searching availability but does not provide explicit when-to-use guidance, alternatives, or exclusions. No information distinguishes this from 'list_lesson_options' or indicates when to prefer 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?

The description discloses that this is a write operation requiring SOCIAL_POSTS_MCP_WRITE_TOKEN, an important auth prerequisite not covered by annotations (none are provided). However, it does not explain conflict behavior, partial-update semantics, or consequences of changing slug/url, leaving some behavioral burden unmet.

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

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

A single front-loaded sentence that names the operation and resource before the auth requirement, with no filler. Every phrase adds signal, and it is appropriately sized.

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 schema has no property descriptions and there are no annotations, the description covers only the core action plus one auth parameter. It omits sibling differentiation, required-field rationale, key/conflict semantics, and parameter details, so it is not complete enough for reliable invocation despite the output schema reducing the need to document 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?

Schema description coverage is 0%, and the description only explains write_token. The meanings and relationships of coach_slug, platform, title, slug, url, is_active, description, and channel_type are left to inference from parameter names, which is insufficient for a nine-parameter upsert.

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 or update') and resource ('social channel/group') and ties it to trainer posts, so an agent knows what entity is being managed. However, it does not explicitly differentiate from the similarly named sibling upsert_trainer_social_link, so it stops short of a 5.

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

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

No guidance on when to use this tool versus alternatives; it does not contrast with upsert_trainer_social_link or other sibling tools. The only usage hint is the required write_token, which is a prerequisite rather than a selection rule.

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, but it only reveals that the operation is an upsert and requires a specific token. It does not disclose what happens to an existing link, whether the operation is idempotent, or any side effects beyond add/update.

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 concise sentence with the action and resource front-loaded. The odd 'public round' wording is slightly confusing, but otherwise there is no filler or redundancy.

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

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

For an 8-parameter write tool with no annotations and no parameter descriptions, this definition is incomplete. It omits what 'public round' means, what platform values are valid, and how display_order or is_active affect behavior, leaving an agent to guess from names.

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 should compensate, but it only explains write_token. The other seven parameters (coach_slug, platform, url, label, handle, is_active, display_order) are left entirely to their names and schema defaults.

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 ('Add or update') and a specific resource ('public round social icon link for a Voice School trainer'), which clearly distinguishes it from post-publishing and channel-management siblings. The phrase 'public round' is somewhat ambiguous, but the overall purpose is still evident.

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 about when to use this tool versus alternatives like upsert_social_channel or create_social_post_draft. The intended use is only implied through the resource name, with no explicit conditions or 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?

With no annotations, the description carries the burden of disclosing behavior. 'Public description, policy, and catalog links' suggests an informational, read-only operation, but it never explicitly states that no data is modified or how the language parameter affects the output.

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 concise sentence with no filler and the core subject is front-loaded. However, it is a noun phrase rather than a full behavioral statement, which slightly reduces clarity.

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 an output schema exists, the description lacks usage context and fails to explain when to call this tool relative to siblings. It also omits the language parameter's role, leaving the description incomplete for effective tool selection and 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 only parameter, language, is not mentioned in the description. The schema provides only the property name and default 'en', with 0% description coverage, so the description does not compensate by clarifying supported values or effect on results.

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 identifies the resource (Voice School online vocal lesson requests) and states that the tool provides public description, policy, and catalog links. This distinguishes it from sibling tools (create, list, search), though it lacks an explicit verb like 'get' or 'retrieve'.

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. The description does not mention that it should be called before creating or searching for lesson requests, nor does it reference the sibling tools.

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