Postlyra

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds genuinely useful behavioral context beyond that: the blast radius is scoped to a single publication ('Other destinations stay unchanged') and prior reads are required — important for a destructive, idempotent write. It stops short of explaining failure/conflict behavior for a destructive op.

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

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

Three short sentences, front-loaded with the activation condition, then the scope constraint, then the prerequisite. No filler and no repetition of schema or annotation content.

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

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

An output schema exists, so return values need no explanation, and the description covers trigger, scope, and prerequisites for a two-parameter tool. The one real gap is the semantics/failure mode of expectedRevision, which matters given destructiveHint=true.

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

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

Schema description coverage is 0%, so the description must compensate, and it only partially does: it names publicationId and points the agent to 'read the post revision and publicationId first', hinting where the values come from. It never explains expectedRevision as an optimistic-concurrency guard, which is critical for a destructive tool that should fail rather than clobber a newer revision.

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

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

The description names a specific verb (apply) and a precise resource scope (a working post revision to ONE selected scheduled or delivered Telegram publication), and the clause 'Other destinations stay unchanged' pins down what is not touched. It is clearly distinguishable from broader siblings like update_post or update_post_draft, but it never names an alternative explicitly, so sibling differentiation is implicit rather than stated.

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

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

It gives an explicit trigger condition ('Use when the author explicitly asks to apply a working post revision to one selected... publication') and a prerequisite ('Read the post revision and publicationId first'), which tells the agent to gather inputs before calling. It does not, however, contrast this with update_post, update_post_draft, or publish_post, so the agent gets a when but not a when-instead-of.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds genuinely new behavioral context: pending publications are cancelled, already-delivered Telegram messages survive, and the action is reversible via restore_post. That is exactly the destruction/retention detail an agent needs before calling a destructive 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?

Three short sentences with zero filler; the trigger condition is front-loaded, followed by effect and recovery path. Nothing repeats the name or title.

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

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

An output schema exists, so return values need no explanation. The description covers side effects, retention behavior, and the undo path, which is everything an agent needs to invoke this destructive tool 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%, and the description never mentions the single required postId parameter or its format/constraints (1-128 chars). The name is largely self-evident, but the description does nothing to compensate for the documentation 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?

Names a specific verb+resource (archive a post) plus its side effect (cancel pending publications), and explicitly distinguishes itself from the sibling restore_post. An agent can route to it without opening any schema.

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

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

Gives a clear trigger condition ("when the author asks to archive a post") and points to the inverse operation via restore_post. It does not contrast against other removal-adjacent siblings such as cancel_publication or delete_publication, so the when-not guidance is incomplete.

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

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

Annotations already declare the safety profile (not read-only, not idempotent, not destructive, closed-world). The description adds genuine beyond-annotation context: images/videos become media blocks while other files become a link, and it explicitly does not publish or alter existing delivery snapshots. It stops short of explaining the revision-conflict error behavior.

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

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

Four short, front-loaded sentences with no filler; the 'Use when' clause leads and each subsequent sentence adds scope or effect. Slightly clipped phrasing ('Read the post revision first') costs it the top mark.

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

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

An output schema exists, so return values need no explanation, and annotations cover safety. For a three-parameter mutation tool the description conveys trigger, prerequisite, side effects, and scope boundaries; only the concurrency-failure contract and the sibling distinction are missing.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It partially compensates by qualifying mediaId as a 'finalized owner mediaId' and hinting at expectedRevision via 'Read the post revision first', but it never defines formats, the revision-mismatch contract, or postId/postId-vs-draft semantics.

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: adding a finalized owner mediaId to a working post, with concrete effects (media blocks vs link). It is clear enough to distinguish from generic post tools, but it never differentiates itself from the near-identical sibling attach_media_to_draft, which is a real ambiguity here.

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

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

It gives an explicit trigger ('Use when adding a finalized owner mediaId to a working post') plus a prerequisite ('Read the post revision first'). However, it offers no exclusions or alternative routing, notably failing to say when to use this versus attach_media_to_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?

Annotations only cover the safety profile (readOnly=false, destructive=false, idempotent=false), so the description adds real value: a hard six-file cap, per-file format/10 MiB limits, an explicit 'Never publishes' guarantee, the returned display instructions, and error handling via nextAction. It stops short of explaining duplication behavior implied by idempotentHint=false.

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 usage trigger and limits, and no sentence is pure filler. The back half is a run-on of abrupt imperatives ('Include the image... Inspect preview_post. On error follow nextAction...') that makes the ordering harder to follow.

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 an output schema exists, the definition needn't explain return values, yet it still covers limits, the exact-placement alternative, preview verification, and error recovery. An agent has enough to call it correctly, though the sibling distinction remains unexplained.

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

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

With 80% schema coverage the baseline is 3, but the description usefully consolidates the two input paths ('mediaFile1..mediaFile6 or mediaFiles') and the six-file total cap into one sentence. It largely reinforces rather than extends the schema text on those fields.

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 ('attach media' to a 'draft') and frames the core constraint ('while preserving draft text'). It does not, however, distinguish itself from the sibling 'attach_media', leaving the agent to infer which of the two to pick.

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

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

Opens with an explicit trigger ('Use this when adding images while preserving draft text') and routes the exact-placement case to update_post_draft with richDocument and slot bindings. It gives a clear context but no exclusion relative to the similarly named attach_media sibling.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: it clarifies that the source post and its history survive, and that in-flight publications are an un-cancelable state. No side effects on the underlying content are left ambiguous.

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

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

Three short sentences, front-loaded with the usage trigger, then the guarantee, then the limitation. No filler or 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description supplies the precondition (must be pending) and the post-condition (source post preserved), leaving only cross-tool routing to siblings unaddressed.

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

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

Schema description coverage is 0% and the single parameter (publicationId) carries no documented constraints in either schema or description. The description's scoping phrase 'one pending publication' implicitly identifies the target, and the parameter name is largely self-describing, but it never states the expected ID format or source.

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 scope ('cancel one pending publication') and adds a distinguishing behavioral trait ('Preserves the source post and its history') that sets it apart from delete_publication without naming it. Clear, though the sibling contrast is left implicit.

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

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

'Use when the author asks to cancel one pending publication' gives a clear triggering context, and 'A publication already being sent cannot be canceled' is an explicit when-not condition. However, it never names the neighboring alternatives (delete_publication, reschedule_publication) that an agent might otherwise choose.

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

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

Annotations already declare it is a non-read-only, non-destructive, non-idempotent write, but the description adds real substance beyond them: what is deep-copied (formatting, media, buttons) and what is deliberately excluded (publication jobs, publishing). It does not mention permissions or that repeat calls yield multiple drafts, but the copy-scope disclosure is the key behavioral fact an agent needs.

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, front-loaded with the usage condition and then the copy semantics. Every clause carries distinct information with no repetition of the name or title.

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

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

For a two-parameter copy tool with an output schema (so return values need no explanation) and annotations covering the safety profile, the description supplies the essential facts: source, destination type, copied content, and exclusions. Only the optional title parameter is left implicit.

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

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

Schema description coverage is 0% and the description names neither parameter. 'Reusing an existing post' loosely implies postId is the source, but the optional title parameter for the new draft is completely unaddressed in both schema and prose, so the description fails to compensate for the zero-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 (copy) and resource (post) and immediately scopes it as producing 'a new independent draft', which separates it from create_post_draft. It also enumerates exactly what is carried over (formatting, media, buttons), so the agent knows what a copy means without opening anything else.

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

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

Gives a clear triggering condition: 'Use when reusing an existing post as a new independent draft.' It also rules out the publication path ('does not ... publish'). However, it never names an alternative tool (e.g. create_post_draft for net-new posts) or states when to prefer one over the other, so the routing guidance 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?

Annotations declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, covering safety, but the description adds the two-step upload behavior, the short-lived nature of the URL, and the important caveat that server-side filesystem paths are unreadable. That goes meaningfully beyond the annotations.

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

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

Three short sentences, front-loaded with the when-to-use condition, then mechanism, then the critical constraint. No filler words; every sentence earns its place.

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

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

For a create tool with an output schema, the description covers the when, the return shape, the follow-up step, and a key constraint. It is nearly complete, though it could mention parameter expectations (e.g., that sizeBytes should match actual bytes) and that the returned URL and headers must be used verbatim. Still, it is strong.

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

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

Schema description coverage is 0%, so the schema itself provides no per-parameter semantics. The description implies but does not document the parameters; it does not clarify fileName, contentType, sizeBytes or category meaning. Baseline 3 is appropriate given the schema carries the names but no descriptions.

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

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

The description states a specific verb+resource: it prepares a media upload and returns a short-lived PUT URL, headers and uploadIntentId. It clearly distinguishes itself from the sibling finalize_media_upload and from attach_media by making this the first step in a two-phase upload flow.

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

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

It explicitly says 'Use when uploading a local image, video or document from any MCP client', and adds the critical exclusion 'A local filesystem path cannot be read by the server.' It also names the follow-up tool (finalize_media_upload), giving a clear sequence.

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

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

Annotations declare non-readOnly, non-idempotent, non-destructive. The description adds meaningful context beyond annotations: 'Never publishes' clarifies the boundary between drafting and publish_post/schedule_post, and it discloses the richDocument precedence rule and the required final-answer image handling. It doesn't mention rate limits or auth needs, but the safety-critical boundary is 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?

Dense and front-loaded, but it packs workflow instructions, output handling, and image-answer rules into one run-on description. Every sentence is relevant but the overload of procedural guidance makes it harder to scan; some content could be trimmed or split.

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 17 params, nested objects, an output schema, and the complex richDocument workflow, the description covers the key procedural requirements: prerequisite tool, precedence rules, media binding, final-answer image inclusion, and the no-publish boundary. It is complete for a tool of 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 coverage is 76%, so the schema carries most parameter meaning. The description adds a few useful rules (media.src binding via mediaFile slots, richDocument overrides text/preset/template), but most param detail is already in the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource (create post draft) and frames it as building a Telegram post. It differentiates itself from update_post_draft/attach_media_to_draft by describing the drafting task, though it doesn't explicitly name siblings. The core intent is clear.

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

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

Gives concrete sequencing: read get_formatting_capabilities first, prefer richDocument over text/preset/template, inspect preview_post. It names the prerequisite and a related tool but stops short of explicit when-not-to-use guidance or naming alternatives like search_post_drafts.

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

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

Annotations already declare this is a non-read-only, non-destructive write, so the safety bar is lower. The description adds genuinely new context: the resulting template is owner-only and is not published, which is information annotations do not carry. It does not mention duplicate creation despite idempotentHint=false.

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 trigger condition front-loaded, followed by the required inputs and the key side-effect. No filler.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The definition covers the essential call shape and the owner-only/no-publish outcome, but omits the optional metadata parameters and any duplication 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 description coverage is 0% across 5 parameters, so the description must carry the burden. It identifies the two required inputs (name and the document, referred to as "RichDocument" rather than the schema's documentJson) but says nothing about locale, category, or description, leaving three optional parameters undocumented anywhere.

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 ("Creates an owner-only template") and the intended trigger (saving a reusable post layout). It lacks explicit differentiation from update_template/delete_template/list_templates, which the agent must infer from the tool name alone.

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

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

"Use when the author asks to save a reusable post layout" gives a clear usage condition rather than a vague one. It does not name alternatives (e.g. update_template for modifying an existing template) or state when not to use it, so routing still requires some inference.

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

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

Annotations already declare destructive=true, idempotent=true, and openWorld=true, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: the blast radius explicitly excludes the source post and messages in other destinations, telling the agent what is NOT destroyed. It stops short of stating that the published message removal is permanent/irreversible.

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

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

Three short sentences, front-loaded with the precondition 'Use only when the author explicitly asks', followed by the action and the survivors clause. Every sentence carries distinct information with no repetition of the title or schema.

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

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

For a single-parameter destructive tool with annotations and an output schema, the definition covers the precondition, the target, and the unaffected resources – what an agent needs to call it safely. The only gap is not stating whether the deletion is permanent or recoverable, which matters for a destructive operation.

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

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

Schema description coverage is 0% for the single publicationId parameter, so the schema documents only type and length bounds, not meaning. The description partially compensates by indicating the id identifies the previously published message, but adds no format, source, or example. With one parameter and no schema prose, this is adequate but thin.

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 (delete) and a clearly bounded resource: one message previously published by Postlyra, identified by publicationId. It implicitly separates itself from siblings like cancel_publication or archive_post by scoping to already-published messages, though it never names the nearest alternative. Clear and specific, but the sibling differentiation is left implicit rather than stated.

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

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

Gives an explicit precondition – use only when the author explicitly asks to delete – which is stronger than typical 'when to use' text and functions as a guardrail. It does not name cancel_publication or reschedule_publication as the alternatives for other intents, so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds a genuinely non-obvious behavioral fact beyond that: posts already created from the template survive deletion, i.e. no cascading delete. It does not mention irreversibility or required ownership/permissions.

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

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

Two short sentences with zero waste: the trigger condition is front-loaded and the second sentence carries a distinct, useful consequence. Nothing is repeated from the name or annotations.

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

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

An output schema exists, so return values need no explanation, and annotations carry the destructive/idempotent profile. What remains thin is the parameter story (no pointer to list_templates for the ID) and the irreversibility of deletion, but for a one-parameter destructive tool the description is close to sufficient.

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

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

Schema description coverage is 0% and the single parameter templateId has no description in either schema or prose. The phrase 'their saved template' weakly implies the template must belong to the author, but nothing says where to obtain the ID or what format it takes, so the description does not compensate for the coverage gap.

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

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

The description pairs a specific verb (delete) with a specific resource (saved template), and the title narrows the scope to a 'personal' template. It is clearly distinguishable from resource-different siblings like delete_publication or archive_post, 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?

It states an explicit trigger: use when the author asks to delete their saved template. There is no guidance on alternatives (e.g., update_template, list_templates to find the ID) or on when deletion is inappropriate, so it stops short of a 5.

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

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

Annotations cover the safety profile (non-read-only, idempotent, non-destructive, closed-world), and the description adds the failure mode ('expired or invalid uploads are rejected') plus what is actually checked (content, size, ownership). It does not spell out the retry/re-upload path, but that is a meaningful addition beyond the structured hints.

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

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

Three tight sentences: prerequisite first, then verification behavior and output, then failure handling. No filler and nothing buried.

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

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

With an output schema present, the description need not explain the returned mediaId structure, and it correctly focuses on sequencing, verification scope, and rejection behavior. Only the semantics of the input identifier remain thin.

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 uploadIntentId parameter, so the description must carry the load. It implies the identifier originates from the create_media_upload call, which is useful, but never names the parameter or states its format/lifetime.

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 (verify/finalize an uploaded file) and distinguishes itself from siblings by naming both the producer (create_media_upload) and the consumer (attach_media). An agent can place this tool in the workflow without opening any schema.

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

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

Explicitly gives the ordering condition: use after uploading bytes to the URL returned by create_media_upload. It does not state when not to use it or what to do on rejection, but the workflow context is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the substantive detail that authorization flows through Telegram and account linkage, but says nothing about what happens on an unauthorized result or any caveats beyond that.

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

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

A single front-loaded sentence with no filler; the condition and the resource are packed into one clause and nothing is repeated from the schema or annotations.

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

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

An output schema exists, so return values need not be described, and the description covers the tool's scope adequately for a parameterless status check. It could be marginally stronger by indicating what an agent should do when the check fails, but nothing essential 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?

The tool takes zero parameters, so per the baseline there is nothing for the description to clarify. The description correctly avoids inventing inputs and pins the implicit target as the 'current MCP caller'.

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 (check) and a precise resource (whether the current MCP caller is authorized via Telegram and linked to a Postlyra account). No sibling tool covers auth status, so it is unambiguously distinguishable from the post/template/workspace tools listed.

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

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

It gives an explicit use condition — 'use this when you need to check whether the current MCP caller is authorized' — which is a clear trigger. It stops short of any exclusions or alternatives, though in this case no sibling offers an overlapping capability.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world behavior, so safety is covered. The description still adds real value by disclosing an important scope restriction (no private Telegram Business conversations, no sending), which is not implied by the annotations.

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

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

Two sentences, front-loaded with the 'Use when' trigger, and every listed category is meaningful rather than filler. The final exclusion sentence is slightly tacked-on but still earns its place.

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

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

For a simple read-only tool with an output schema (so return format needn't be explained), the description covers purpose scope, triggering conditions, and important exclusions. The only gap is the undocumented locale parameter.

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

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

There is one optional parameter (locale, enum ru/en) with 0% schema description coverage, and the description says nothing about it. The agent gets no guidance on what the locale controls (result language vs. filter) or how omission behaves, so the description 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?

The name/title plus the enumerated categories (unfinished drafts, formatting or media problems, lost permissions, failed deliveries, publication gaps) make clear this retrieves content items that need attention. It is specific about the resource scope, but never states exactly what it returns and does not distinguish itself from siblings like get_post or search_post_drafts.

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 definition is explicitly usage-first, listing concrete triggering situations ('reviewing unfinished drafts, formatting or media problems...'), and adds a negative scope boundary ('Does not read private Telegram Business conversations or send messages'). It stops short of naming alternative tools to use instead, so it is strong but not exhaustive.

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

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

Annotations already establish this as a safe, read-only, idempotent, closed-world call. The description adds genuinely useful context beyond that: it must be called first, once per task, and enumerates the contract contents (blocks, inline marks, nesting, limits, uploads, error recovery, presets, next step). It stops short of stating caching or token-size characteristics of the returned contract.

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

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

Three sentences, all front-loaded: the imperative call-first directive leads, followed by what Postlyra produces and what the return payload contains. Every sentence carries distinct information with no 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?

An output schema exists, so return values need not be detailed, yet the description still summarizes the contract's scope and adds the sequencing rule ('first, once per task'). Nothing an agent needs to invoke this correctly is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond the (empty) schema, and it correctly signals a parameterless call.

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 (get Postlyra formatting capabilities / RichDocument contract) and precisely scopes what it returns. It is clearly distinguishable from the neighboring post/workspace/template mutation tools, none of which expose formatting contracts.

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

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

Explicit when-to-use: 'call it FIRST, once per task' when composing or formatting any post, and a when-not-to-look-elsewhere note ('Telegram MarkdownV2/parse_mode documentation is not needed'). It does not name sibling alternatives, but no real alternative exists for this prerequisite lookup, so the gap is minor.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real context beyond them: it returns the *working document / current revision* and explicitly performs no preview or publish side effect, which distinguishes it behaviorally from preview_post.

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

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

Two tight sentences with zero filler and the primary use condition front-loaded in the first clause. Every sentence 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?

An output schema exists, so return-value explanation is largely unnecessary, though the description helpfully characterizes the returned object as the working document. The remaining gap is the missing semantics for the 'postId' parameter.

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

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

Schema description coverage is 0% for the single required parameter 'postId'. The description never mentions the parameter or its expected format (ID vs slug vs UUID), even though the schema only supplies a length constraint. With a non-trivial required identifier, the description should compensate and does not.

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

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

States a specific verb and resource ('reading an existing post and its current revision'), which lets an agent distinguish it from preview_post, publish_post, and update_post by effect. It stops short of naming the sibling tools it is not, so it is clear but not maximally differentiated.

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 scopes usage to reading before editing, and rules out the adjacent workflows ('without enabling a public preview or publishing anything'), which implicitly routes the agent away from preview_post and publish_post. No named alternatives, but the condition for use is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the content scope (quotas, storage, chat count, time zone), which is modest incremental value, but says nothing about auth requirements, freshness of the data, or failure behavior.

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

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

A single front-loaded sentence with no filler; the 'Use when' prefix puts the trigger first and every listed field earns its place.

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

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

An output schema exists, so return values need not be described, and annotations cover safety. However, for a read tool whose whole purpose is scoping and identity, the description omits that it reflects the authenticated account's workspace and gives no hint of behavior when no workspace is available — minor but real gaps.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4 and no parameter explanation is required.

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 is phrased purely as a trigger ('Use when checking...') and never states the operation — that it returns the current workspace's settings/quotas. The four listed fields imply what the tool surfaces, but the agent must infer the verb+resource, and nothing distinguishes it from siblings such as update_workspace or get_auth_status.

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 a concrete usage context — 'before planning content' — and enumerates the conditions (quota, storage, chat count, time zone) that should prompt the call. It stops short of naming alternatives like update_workspace for changing those settings, so it is strong but not a full when/when-not guide.

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

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

Annotations already establish readOnly, idempotent, non-destructive, and closed-world behavior, so the bar is low. The description still adds a real behavioral constraint not present in structured data: results are limited to channels/groups/chats the *authorized* user can manage, which tells the agent to expect a permission-filtered, potentially empty result and that no auth escalation is described.

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

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

A single sentence with no filler, front-loaded with the usage cue followed by the resource and scope. Nothing is wasted, but the sentence is thin enough that its brevity reflects limited content rather than tight editing.

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

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

For a zero-parameter, read-only listing tool with an output schema present and full annotation coverage, the description supplies everything needed: what is listed, and the permission scope of the listing. Return values are correctly delegated to the output schema.

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

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

The tool takes zero parameters, which sets the baseline at 4. The schema is empty with additionalProperties false, and the description correctly adds no parameter guidance because none is needed, though it also supplies no filtering options the agent might expect (there are none).

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

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

The description names a specific verb ("list") and a concrete resource ("Telegram channels, groups, and chats"), and adds scope the tool name alone does not convey: only assets the authorized user can manage through Postlyra. That scope distinguishes it clearly from the post/publication/template siblings, though it does not explicitly reference any sibling by 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?

"Use this when you need to list..." identifies the triggering scenario but the condition is essentially a restatement of the tool's function. There is no statement of when not to use it or which sibling covers adjacent needs (e.g., listing publications vs. channels), so usage is only implied rather than routed.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description adds real value beyond that by disclosing the return contract ('returns publicationId') and its role as the prerequisite for reschedule/cancel/edit/delete chaining, which annotations cannot express. Pagination behavior is left unstated.

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 usage trigger front-loaded and zero filler; every clause either scopes the tool or explains why an agent would call it.

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

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

An output schema exists, so return-shape explanation is not required, and annotations cover the safety profile. However, with seven undocumented parameters and no enum values, an agent cannot tell how to filter by time range, channel, post, or status, leaving the definition only minimally usable for 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% across 7 parameters, so the description carries the full explanatory burden, yet it never mentions from/to, limit, offset, postId, channelId, or the accepted status values. The phrase 'scheduled publications, delivery failures or messages previously published' only vaguely gestures at the status filter and leaves the time-range and scoping filters 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?

The description gives a specific verb-and-resource framing ('inspecting scheduled publications, delivery failures or messages previously published') and the title reinforces it as a calendar read. It is clearly distinct from write siblings like cancel_publication or reschedule_publication, though it does not name them explicitly.

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

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

'Use when inspecting scheduled publications, delivery failures or messages previously published' states the triggering conditions clearly, and the follow-up sentence implies this is the discovery step before rescheduling, cancellation, editing or deletion. No explicit exclusions or named alternatives are given, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that template ids are returned, but says nothing about pagination, filtering behavior, or ordering that would extend beyond the annotations. Adequate but not rich.

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

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

It is short, but the structure is disjointed: the standalone fragment 'Optional for custom composition' is ambiguous about what is optional and for whom. The actual purpose statement is deferred to the final clause. Every sentence roughly earns its place, but the ordering and fragment hurt 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?

With zero required parameters, an output schema present, and annotations covering safety, the main remaining need is usage routing, which the description supplies. Nothing essential for calling it correctly is missing, though a note on how category/channelId narrow results would round it out.

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

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

Schema description coverage is 100%, so category and channelId are already documented in the schema, and the description mentions neither. The description's note that ids are returned is output-related rather than parameter-level, so it adds no parameter meaning. Baseline 3 applies.

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

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

The description ends with a concrete verb+resource statement: 'this tool lists saved templates and their ids.' It distinguishes itself from get_formatting_capabilities, which is named explicitly. The purpose is clear, though it is buried at the end of the description rather than front-loaded.

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

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

It gives an explicit trigger ('Use this when the user wants an existing reusable Postlyra layout template') and routes the agent away to get_formatting_capabilities for supported blocks and JSON/formatting questions. No explicit when-not condition is given, but the alternative tool is named and the condition that selects it is clear.

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

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

With annotations only covering safety flags, the description adds real behavioral context: it never publishes, it can surface validation warnings, screenshots may be unavailable/truncated and are retryable without recreating the draft, and the result image must be embedded in the final answer. The 'readOnlyHint: false' flag combined with 'idempotent: true' is consistent with an artifact-producing preview rather than a state mutation, so nothing is contradicted.

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 trigger condition, prerequisite lookup and return shape come before the presentation rules. Multiple sentences are justified because each carries a distinct instruction (lookup source, output format, truncation handling, non-publishing guarantee).

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 workflow tool that returns rich artifacts, the description covers the lookup path, the return shape, validation output and how the agent must present the image and link. Some of this duplicates what an output schema would carry, but the agent-facing presentation instructions are not captureable elsewhere, making the definition operationally 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?

Only one parameter exists and the schema gives it 0% description coverage, so the description must carry the load. It does tell the agent where draftId comes from (search_post_drafts), which is genuinely useful, but adds no format or semantic detail about the identifier 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?

The description establishes a specific verb+resource: previewing a saved Postlyra draft, and enumerates what it returns (documentJson/richHtml, native JPEG, display instructions, validation warnings). It clearly scopes to drafts, which usefully disambiguates from search_posts/get_post despite the 'preview_post' name saying 'post'. It stops short of explicitly naming the sibling it differs from.

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 a direct when-to-use ('Use this when previewing a saved draft') and a concrete prerequisite workflow: obtain draftId via search_post_drafts first. It also tells the agent to retry unavailable screenshots without recreating the draft. No explicit when-not-to-use (e.g. published vs. draft posts) is stated, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=true, so the safety profile is partly covered. The description still adds real behavioral context beyond them: idempotencyKey should be reused on retry, and queued/retrying status means pending rather than delivered. It stops short of describing irreversibility or failure modes.

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 usage condition and the safety-critical preconditions, then tacks on retry and status semantics. Four dense sentences with little waste, though the prerequisite list 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?

An output schema exists, so return-value documentation is not required. For a 5-param, destructive, externally-visible write with low schema coverage, the description supplies the authorization gate, prerequisite tool chain, and async status caveat — everything needed to call it correctly.

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

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

Schema description coverage is only 20% (channelId alone is documented), so the description must compensate, and it largely does: it explains channelId resolution via list_channels, the confirmed=true flag, the confirmationText authorization payload, and idempotencyKey retry semantics. draftId itself is never described.

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 (publish a reviewed existing Postlyra rich draft to a connected Telegram channel) and explicitly differentiates itself from the draft tools: 'This is the external publication action; draft tools never send.' An agent can distinguish it from schedule_post, apply_post_to_publication and create_post_draft without opening a schema.

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

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

Gives an explicit precondition for use ('when the user explicitly authorizes publishing a reviewed existing... draft') plus a prerequisite workflow naming sibling tools (resolve channelId via list_channels, inspect via preview_post, supply confirmed=true with confirmationText). Nothing about when-to-use is left to inference.

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

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

Annotations already disclose idempotent=true, destructiveHint=true, and openWorld=false, lowering the burden. The description adds the useful scope constraint "Does not change its content," but says nothing about what happens if the publication is no longer pending or what the destructive hint implies for the prior schedule.

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

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

Three tight sentences: when-to-use first, then required inputs, then a scope boundary. Every sentence earns its place with 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?

An output schema exists, so return values need not be explained. The two params are covered and the non-content-change scope is stated. Minor gaps remain around preconditions (must the publication still be pending?) and the destructive semantics, but overall it is complete enough to invoke.

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

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

Schema coverage is 0%, so the description must carry parameters. It names publicationId and clarifies that scheduledAt must be a concrete ISO date with a UTC offset, which is format detail the bare date-time schema does not convey. This meaningfully compensates for the missing schema descriptions.

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

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

States a specific action (change date/time) on a specific resource (one pending publication), which naturally distinguishes it from schedule_post and cancel_publication. It stops short of naming those siblings explicitly, but the verb+resource+scope combination is unambiguous.

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

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

"Use when the author asks to change the date or time of one pending publication" gives a clear triggering condition and implicitly limits it to pending items. It does not name alternatives (schedule_post, cancel_publication) or state when-not to use it, so it falls short of the top band.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond the annotations — canceled publication jobs are not restarted — and clarifies the resulting state is a working draft.

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 tightly written sentences, front-loaded with the usage condition, and every clause contributes new information (draft outcome, canceled-job behavior) with 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 and annotations covering idempotency and destructiveness, the remaining burden is light. The description covers the trigger, the outcome state, and one edge behavior, though it omits error conditions (e.g., what happens when the post is not archived) and permission requirements.

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?

One parameter at 0% schema description coverage, so the description must carry the load. It implies the postId must reference an archived post, which is meaningful, but adds no format, length, or error-handling detail for the ID 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?

The description gives a specific verb (restore) and resource (an archived Postlyra post) plus the resulting state ('as a working draft'), which is more than a restatement of the name. It implicitly contrasts with archive_post but never names a sibling, so it falls short of full differentiation.

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

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

'Use when restoring an archived post' supplies a trigger condition (only applies to archived posts), but there is no when-not guidance, no mention of archive_post as the inverse operation, and no prerequisites such as permissions.

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

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

Annotations already declare idempotentHint, destructiveHint and openWorldHint, so the safety profile is largely covered. The description adds meaningful behavioral context beyond that: the server applies shared publishing rules and stores an immutable delivery snapshot, and it flags the idempotency requirement. It still does not explain reversibility or how cancellation interacts with the snapshot.

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

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

Three tight sentences with the usage condition front-loaded, followed by input constraints and behavioral notes. No filler; each sentence adds information. Slightly dense but well ordered.

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

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

An output schema exists, so return values need no explanation, and annotations cover the mutation/idempotency profile. Still, for a 6-parameter mutation linking a post and channel at a scheduled time, the description omits expectedRevision's role and the postId/channelId relationship, leaving noticeable gaps.

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

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

Schema coverage is only 17% — just the timezone field is documented — so the description must compensate and only partly does. It clarifies the scheduledAt format (exact ISO date with UTC offset) and the idempotency key requirement, but postId, channelId and expectedRevision carry no semantic explanation in either place.

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: scheduling a post to a connected channel or group. This is clearly distinct from publish_post or reschedule_publication in intent. It stops short of explicitly naming how it differs from those siblings, so it is clear but not fully self-differentiating.

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 supplies a trigger condition, 'when the author explicitly asks to schedule a post,' which is useful guidance. However it names no alternatives (publish_post, reschedule_publication) and gives no when-not guidance or prerequisites such as channel connectivity or permissions.

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?

Adds meaningful context beyond annotations: empty query behavior, case-insensitive and order-independent matching, owner-only results, newest-first ordering, and pagination semantics (continue with nextCursor if hasMore, even on an empty page). It also clarifies what the tool does NOT do ('Never edits, enables sharing or publishes'), which is behaviorally useful, though annotations already cover the read-only/non-destructive profile.

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, front-loaded, and every sentence carries distinct information: trigger, precondition, matching semantics, empty-query behavior, return shape, pagination, and next tool. No repetition of schema defaults or filler.

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

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

Complete for a read-only search tool with an output schema: the description covers when to use it, matching behavior, empty-query fallback, owner-only scope, ordering, pagination, and the follow-up action. Output schema carries return details, so the description need not repeat them.

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

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

Schema coverage is 100%, so baseline is 3. Description adds some beyond-schema semantics: empty query lists recent drafts (matching query default), cursor continuation logic, and match semantics ('matches all keywords or word fragments in any order, case-insensitively, in title and full rich text') that go beyond the schema's per-parameter descriptions.

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

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

States a specific verb (search/find) and resource (drafts) with scope (title and full rich text, keyword fragments, any order). It distinguishes itself from search_posts by specifying drafts only and from update_post_draft/preview_post by positioning itself as the lookup step before those actions.

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

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

Explicit when-to-use ('when finding an existing draft by topic, title or content before previewing or editing it'), explicit precondition ('Search first when draftId is unknown; do not ask for a link'), and explicit next steps ('use preview_post for the selected draft'). Alternatives and exclusions are plainly stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds that it searches owner content and the archived scope, but says nothing about pagination behavior (limit/offset) or result ordering, which would be the useful additions.

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

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

Three short sentences, front-loaded with the usage trigger, then the searchable facets, then the follow-up tool. No filler and nothing repeated from the schema or annotations.

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

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

With an output schema present, return values need no explanation, and the annotations cover safety. The remaining shortfall is pagination and includeArchived semantics on a schema with zero parameter descriptions, but the core search behavior is adequately conveyed.

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

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

Schema description coverage is 0%, so the description must carry the burden. "by words, status, connected channel and update dates" maps to query, status, channelId and from/to, covering the main filters, but limit, offset and includeArchived are left unexplained for an 8-param tool.

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 (find/search) and resource (Postlyra post) and even clarifies the scope: scheduled, published or archived content. It routes to get_post as the follow-up reader. However, it never distinguishes itself from the closely-named sibling search_post_drafts, leaving that differentiation to inference.

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

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

"Use when finding any existing Postlyra post" gives clear context, and "Read the selected post with get_post" names the alternative for retrieval after selection. The one obvious gap is the sibling search_post_drafts, whose relationship is not addressed, so there are no explicit exclusions.

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

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

Annotations declare a non-read-only, non-idempotent, non-destructive mutation, and the description adds behavior beyond that: revisions must be read first (optimistic concurrency), and scheduled/sent messages stay on their snapshots until apply_post_to_publication is invoked. It doesn't describe rate limits or error outcomes, but the snapshot semantics are genuinely useful context.

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

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

Three tight sentences: the trigger, the precondition, and the snapshot caveat are front-loaded and each earns its place. No restating of the name or schema.

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

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

Given an output schema exists, the description needn't explain return values, and it covers the key behavioral caveats (revision, snapshots). What remains thin is the parameter-level meaning for a 7-param tool with only 14% schema coverage, though the field enumeration partially covers that.

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

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

Schema description coverage is only 14%, so the schema mostly does not document parameters. The description compensates by listing editable fields (title, buttons, attention flag) and mentioning the revision requirement, but leaves locale, documentJson provenance, and inlineButtons structure unexplained. This is adequate but incomplete against 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 ('changing a post's working content, title, buttons or attention flag') and enumerates the mutable fields, so the agent knows exactly what gets edited. It doesn't explicitly name a sibling tool, but the fields and scope make its role distinct from update_post_draft or copy_post.

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 trigger is explicit ('Use when changing a post's working content'), and it names a precondition ('Read its revision first') plus an alternative pathway ('until apply_post_to_publication is requested'). No exclusions for when-not-to-use are given, keeping it short of a 5.

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

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

With annotations already declaring readOnlyHint=false and destructiveHint=false, the description adds real behavioral context: complete replacement of richDocument, preserving untouched content and stored media URLs, text replacing layout, media binding rules, and the never-publishes guarantee. These non-obvious side effects are the value-add, though the exact output/response contract is left to the output schema.

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

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

Compact and dense, with the usage trigger front-loaded and operational sequencing packed into short clauses. It is effective but slightly telegraphic — the second half reads as a list of imperatives (Import files, Include the image, Inspect preview_post) that could be structured more clearly.

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 15-parameter mutation tool with a complex nested richDocument and an output schema present, the description covers the critical authoring workflow, preserve-what-you-don't-touch behavior, media binding, and the no-publish guarantee. Return values are rightly deferred to the output schema, leaving only minor gaps such as idempotency/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?

Schema description coverage is 73%, so the schema carries much of the load, but the description adds meaning beyond it: 'text replaces layout', richDocument must be the complete edited document started from preview_post.documentJson, media files bind as media.src, and instructions is limited hints only and does not run an AI editor. These clarify non-obvious interactions between parameters that the schema alone does not convey.

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 name and title say 'update a post draft', while the description opens with 'Use this when editing a draft' — a usage trigger rather than a clean statement of what the tool does. It implies a draft-editing/update operation but never states plainly that it modifies an existing draft by id, and it does not differentiate itself from siblings like update_post, attach_media_to_draft, or create_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?

It names prerequisites (read preview_post and get_formatting_capabilities first) and routes image-only additions to attach_media_to_draft, which is genuine when-to-use guidance. It stops short of saying when not to use it (e.g. versus update_post or create_post_draft), so it is clear context but incomplete exclusions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description usefully adds an authorization constraint (only the author's own templates are mutable). However, it says nothing about partial-update behaviour - whether omitted fields are preserved or cleared - which matters for a mutation tool whose annotation claims idempotency.

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 use condition front-loaded ahead of the restriction. Nothing could be trimmed without losing information.

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

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

An output schema exists, so return values need not be explained, and the annotations carry the mutation/safety profile. But for a 6-parameter update with 0% schema coverage, the description omits the editable field list and the partial-vs-full update semantics an agent needs to call it correctly.

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

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

Schema description coverage is 0% across six parameters, so the schema contributes no per-parameter meaning and the description must compensate. The description names no parameter at all, leaving name, locale, category, description and documentJson - plus the nested documentJson object - undocumented in both places.

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 ('changing') and resource ('the author's saved template'), and the title 'Edit a personal template' narrows it to the owner's own templates, distinguishing it from create_template, delete_template and list_templates. It stops short of naming which fields are editable, so it is clear but not maximally specific.

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

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

The opening clause gives an explicit use condition ('Use when changing the author's saved template'), and the second sentence supplies a concrete exclusion: system templates and other users' templates cannot be edited. No sibling alternative is named for the excluded cases (e.g. copy the template), so routing is clear but not complete.

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

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

Annotations already declare this is a non-destructive, idempotent write, so the safety profile is covered. The description adds one genuinely useful behavioral constraint (existing publication times are untouched), but says nothing about partial-update semantics (whether omitted fields are left unchanged) or required permissions.

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

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

Two sentences, front-loaded with the trigger condition and followed by a scope exclusion. No filler and 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?

An output schema exists, so return values need not be explained, and annotations cover the mutation safety profile. What remains thin is the partial-update contract and the undocumented parameters, but for a 3-param preference patch tool the description is close to sufficient.

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

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

Schema coverage is only 33%: timezone is documented in the schema (IANA format, UTC storage), while cadencePerWeek and remindersEnabled have no schema descriptions. The description compensates partially by mapping plain-language concepts ("weekly publication target", "content reminder preference") onto those two params, but gives no units, bounds, or boolean semantics.

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 (change/update) and enumerates the three resources affected: account time zone, weekly publication target, and content reminder preference. This lets an agent distinguish it from publication/post editing siblings, though it never explicitly names or contrasts those 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?

"Use when the author asks to change..." provides a concrete trigger condition, and "Does not change existing publication times" serves as an exclusion boundary that steers publication-time edits elsewhere (e.g., reschedule_publication). It stops short of naming that alternative explicitly, so it is clear context without full routing.

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