Postlyra.app — Telegram posts from AI chats

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 signal a non-readOnly, idempotent, non-destructive mutation, and the description reinforces this with a valuable side-effect statement: 'Previously queued publication snapshots remain unchanged. Never publishes.' This tells the agent the change is scoped to future content and has no publishing side effect, adding real context beyond the annotations. Permission/auth requirements are still undisclosed.

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 dense, front-loaded sentences that lead with the use case and then branch on target/mode; every clause carries information and nothing is redundant. Minor terseness ('inherit follows their defaults') slightly hurts readability but not economy.

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 needn't explain returns, and it covers the mutation's side-effect boundary and mode semantics well. The only real gap is the undocumented draftId/channelId parameters, which leaves the definition slightly under-specified for a 4-parameter tool.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains the enums that matter — target values (default/channel/post) and selection.mode (inherit/none/custom) plus signatureId — but leaves draftId and channelId entirely undocumented, so half the parameters remain opaque in both schema and description.

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

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

States a specific action (assign a signature) and its three scopes (account default, channel override, single-post override), so an agent knows exactly what the tool mutates. It clearly reads as a configuration-assignment tool rather than a create/update-signature tool, though it never names the sibling tools (create_signature, update_signature) it must be distinguished 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?

'Use this when managing post auto-signatures' plus the per-target rule ('For default use custom/none; for channel/post inherit follows their defaults, none disables it, custom selects signatureId') gives explicit conditional guidance on which mode to pick per target. There is no naming of alternatives or exclusions, 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 the mutation is non-read-only, non-destructive, and non-idempotent. The description adds meaningful context beyond that: it explains how different media types map to block types and explicitly states it does not publish or change existing delivery snapshots, plus implies optimistic concurrency via 'read the post revision first'.

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

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

Three tightly written sentences, front-loaded with the usage condition, followed by prerequisite, behavioral mapping, and scope boundary. No filler or redundancy.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. Still, for a mutation tool with a close sibling (attach_media_to_draft), the description lacks explicit sibling differentiation and parameter detail, leaving some ambiguity about when to use this versus its counterpart.

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 gives partial cues: mediaId is a 'finalized owner mediaId', postId is a 'working post', and expectedRevision relates to reading the post revision first. But it omits format details, constraints, and what 'owner' entails, leaving significant gaps for an undocumented schema.

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

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

States a specific verb (adding) and resource (finalized owner mediaId to a working post). However, it does not differentiate from the sibling attach_media_to_draft, leaving ambiguity about which attachment tool to use in a given context.

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

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

Provides a clear when-to-use context ('adding a finalized owner mediaId to a working post') and a prerequisite ('Read the post revision first'), but offers no explicit alternatives, when-not-to-use conditions, or guidance on choosing between this and 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 already declare write/openWorld/non-idempotent/non-destructive, but the description adds real behavioral context beyond them: inputs are downloaded, validated and imported before success and "failure attaches nothing" (atomicity), and it "Never publishes." It also signals the return preview and that error nextAction should be followed.

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-loads the when-to-use condition before constraints and fallbacks, and every clause carries information. It is dense to the point of terseness in places ("Returns JPEG/public preview; follow display instructions"), which slightly obscures meaning but wastes little space.

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 10-parameter nested-object mutation with an output schema present, the description covers the critical gaps: atomicity, format/size limits, the alternative for exact placement, and the no-publish guarantee. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 80%, so the baseline is 3, but the description adds genuine meaning: the mediaFile1..6/mediaFiles equivalence, the six-file aggregate cap, format/size limits, and direct references[].url usage. It stops short of explaining placementHint's legacy status here, leaving some redundancy with the schema.

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

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

States a specific verb (attach), resource (media), and target (draft) plus the distinguishing scope: "adding images without replacing draft text." This clearly separates it from update_post_draft (text/placement) and the sibling attach_media, so an agent can route 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?

Opens with an explicit when-to-use condition and names the alternative for a different intent ("For exact placement use update_post_draft with richDocument file-slot bindings"). Constraints (six total, JPEG/PNG/GIF/WebP, 10 MiB each) further bound correct invocation.

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 destructive=true, idempotent=false, openWorld=true, so the bar is lower; the description still adds real value by naming the concrete side effects (archives the original draft, revokes its preview) and stating it never publishes. It does not mention that archive/revoke are irreversible or repeat-call implications for non-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?

Three dense sentences that front-load the trigger and follow with the transformation and guard clause; minimal waste. The opener 'Use this when managing post auto-signatures' is somewhat generic filler relative to the specificity that follows.

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?

Output schema exists so return values need not be explained, and the annotations cover the safety profile; the description supplies the missing preconditions and side effects. The only gap is the undocumented 'title' 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%, so the description carries the burden. It explains 'default' (assign as account default) and 'channelIds' (owner-bound), and draftId is self-evident, but the 'title' parameter is never mentioned in either schema or description.

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

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

States a specific verb (convert) plus resource (unpublished inactive draft → reusable auto-signature) and enumerates the side effects (archive draft, revoke preview). An agent can distinguish it from create_signature and archive_post from the description 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?

Gives a clear precondition — the source must be an unpublished inactive draft — and clarifies it 'Never publishes,' which steers the agent away from publish_post. It does not explicitly name the alternatives (create_signature, archive_post) for the case where no draft exists, 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 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 already establish the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent), so the bar is lower. The description adds real behavioral value on top: the return payload (short-lived PUT URL, headers, uploadIntentId), the required follow-up step, and the important constraint that the server cannot read a local filesystem path. Auth requirements and URL expiry semantics beyond 'short-lived' are not stated.

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

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

Three tightly packed sentences with no filler; the trigger condition, the return contract, the next step, and the filesystem constraint are all front-loaded in roughly the order an agent needs them.

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, yet the description still summarizes them usefully. Combined with the workflow sequencing and the local-path caveat, an agent has enough to invoke this correctly; the only missing pieces are failure modes and parameter constraints that the schema does not supply.

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 four parameters, so the description carries the burden. It partially compensates by enumerating the accepted media kinds, which maps to most of the category enum, and by clarifying via the 'local filesystem path cannot be read' note that fileName is a name rather than a path. It says nothing about sizeBytes limits or the expected contentType format, leaving genuine gaps.

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

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

States a specific verb and resource ('prepare a media upload') and immediately names its counterpart, finalize_media_upload, making the two-step flow unambiguous. It also enumerates the supported asset kinds (image, video, document, audio, voice), so an agent can distinguish this from the unrelated attach_media/attach_media_to_draft 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?

Gives a clear when-to-use trigger ('uploading a local image, video, document, audio or voice file') and spells out the required follow-up call to finalize_media_upload. It does not, however, explain when to prefer this over siblings such as attach_media or attach_media_to_draft, so the routing decision is only partially covered.

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

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

Beyond the annotations (readOnly=false, destructive=false, openWorld=true) the description discloses that the call returns an ID, JPEG, preview link and its own card on MCP Apps hosts, that image inputs are validated and durably imported while external media.src may stay external, that validation must be checked, and that it never publishes. These are concrete behavioral facts annotations cannot express.

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

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

The use case is front-loaded and every clause carries operational weight for an 18-parameter tool, so little is wasted. The delivery is a run-on of semicolon-joined imperatives rather than grouped guidance, which costs it a point on structure.

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

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

For a complex, nested, openWorld tool with an output schema, the description covers the critical inter-tool dependencies (get_formatting_capabilities, show_post_card suppression, media binding). Minor omissions remain, such as defaulting behavior for style/language and how this tool relates to attach_media_to_draft or preview_post, but nothing needed to call it correctly is missing.

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

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

Schema coverage is 72%, and the description adds real meaning on top of it: mediaFile1..6/mediaFiles are bindable as richDocument media.src slots, richDocument overrides text/template/preset, and reference images are downloaded and imported. It does not clarify style vs formatPreset interplay or signatureSelection, but it usefully compensates for the uncovered gaps.

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

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

The first clause 'Use this when creating a Telegram draft' names the verb and resource clearly, and 'Never publishes' implicitly distinguishes it from publish_post/schedule_post. However, it never states plainly that the tool *creates* a draft record, so an agent must infer the action from the use-case framing rather than a direct statement.

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

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

Explicit routing: use for Telegram drafts, read get_formatting_capabilities first, prefer a finished richDocument, bind media via media.src slots, and specifically do NOT auto-call show_post_card because it duplicates the returned card. This is exactly the when/when-not/alternatives guidance the dimension rewards.

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

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

Annotations already declare readOnly=false, destructive=false and non-idempotent, so the safety profile is covered. The description adds genuinely non-obvious behavior: 'Never publishes', which tells the agent this write is inert with respect to live posts. It omits auth/permission requirements and any storage-quota limits, so it is not exhaustive.

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

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

Three short sentences, all front-loaded with the action before the follow-up pointer. The trailing 'Never publishes' is a slight orphan fragment, but nothing is wasted and there is no filler.

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

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

An output schema exists, so return values need not be described, and annotations cover the mutation profile. For an 11-parameter nested-object creation tool the description supplies the workflow (create then assign_signature) and the inertness guarantee; only the media-slot mechanics and permission prerequisites are left entirely to the schema.

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

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

Schema coverage is 64% and the schema itself carries the heavy detail (media slot names, mime types, size limits, mediaFile1-6 vs a mediaFiles array capped at 6). The description adds no syntax or constraints beyond naming 'RichDocument and optional buttons/media', which mirrors the schema rather than extending it.

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: 'Create a reusable auto-signature with the post editor's full RichDocument and optional buttons/media.' This distinguishes it from read/update/delete signature siblings and from post-draft tools. It does not explicitly differentiate from convert_draft_to_signature, which is the nearest ambiguous sibling, so it stops short of a 5.

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

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

It gives clear context ('Use this when managing post auto-signatures') and routes the agent to the follow-up step ('Assign it with assign_signature'). It never states a when-not condition, e.g. use convert_draft_to_signature when you already have a draft, which would be required for 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 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 genuinely new behavior beyond that: bindings are cleared, existing publication snapshots retain their original content, and it never publishes — non-obvious consequences of a destructive call.

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

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

Four short sentences, front-loaded with the action and followed by constraints and side effects. No filler, though the opening 'when managing post auto-signatures' clause carries little 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 described, and the description covers the important post-conditions (bindings cleared, snapshots unaffected, no publish). Missing only auth/permission expectations and how to source the signatureId.

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 signatureId parameter, and the description never mentions it — not its format, nor how to obtain a valid id (e.g., from list_signatures). With low coverage, the description is expected to 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 ('Delete an owner-bound auto-signature') and adds scope ('owner-bound', 'clear its bindings'), so an agent can distinguish it from create_signature, update_signature, and get_signature. It stops short of naming those siblings explicitly, which keeps it from a 5.

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

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

'Use this when managing post auto-signatures' is close to tautological and gives no when-not conditions or alternatives. The real guidance is implicit: only owner-bound auto-signatures can be deleted, and deletion never triggers a publish. That is usable but indirect.

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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new context the annotations cannot express: the same-account prerequisite and the visibility limitation for other accounts' chats.

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 sentences, front-loaded with the trigger ('Use this when...') and followed by purpose, prerequisite, and caveat. No filler, though the visibility caveat and the same-account requirement are close enough in meaning to be consolidated.

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 the safety profile, the description need not explain return values. It covers when to call and the account-scoping constraint; the only soft spot is that 'auth status' is described purely as an account label, leaving the nature of the 'status' itself slightly 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-argument tool 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 states a specific verb and resource: checking the verified Telegram account linked to this AI connection, and returning its label. That is clear enough to distinguish it from sibling listing tools like list_channels, 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 gives concrete trigger conditions ('when introducing Postlyra or resolving missing channels') plus a precondition ('the bot must be opened under the same account') and an exclusion ('chats connected under another account are not visible here'). No alternative tool is named for the non-matching case, 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, 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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context: it is a one-time-per-task priming call and enumerates the contract contents. It stops short of stating pagination/rate/caching specifics, so a 4 rather than 5.

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

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

The critical usage instruction (call FIRST, once per task) is front-loaded in the opening clause. A few of the later enumerations of contract contents are slightly list-heavy, but every sentence conveys a distinct fact and nothing is redundant.

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

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

With an output schema present the return values need not be explained, yet the description usefully summarizes what the contract covers and how the agent should consume it. Nothing essential for correct invocation is missing for a zero-parameter priming tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. The description correctly does not invent parameter behavior.

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

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

States a specific verb and resource — returns the complete RichDocument formatting contract for Postlyra posts, including block/inline mark JSON, nesting, limits, uploads, error recovery and presets. It is clearly distinguishable from siblings like preview_post or create_post_draft because its output is a schema/contract rather than post content.

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

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

Explicitly says to call it FIRST and once per task when composing or formatting any post, and tells the agent what not to rely on ('Telegram MarkdownV2/parse_mode documentation is not needed'). It even points toward follow-up action ('which tool to use next'), giving unambiguous when/when-not guidance.

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

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

Annotations already 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 and destructiveHint=false, so the safety profile is covered; the description still adds meaningful scope information by stating it is "Public help only: reads no user data and never sends." It also discloses the default behavior ("Defaults to a short quickstart"), which is not derivable from the annotations alone.

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, then defaults, then coverage, then the sibling hand-off — a sensible priority order with no filler sentences. It is however a dense run-on of semicolon-linked clauses that takes some parsing to extract the level mapping.

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-required-parameter documentation lookup with an output schema (so return shape needs no explanation), the description supplies everything needed: when to call, the default response size, how to escalate detail via level/topic, content coverage, and the boundary with get_formatting_capabilities.

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 semantic weight, and it does for the most consequential parameter: level is disambiguated as quickstart=short, workflows=steps, reference=examples, plus the documented default. Topic values are only loosely gestured at via the coverage list (media, buttons, consent) and locale is unexplained, so the compensation is partial rather than complete.

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 the Postlyra usage guide) and enumerates the subject matter it covers: onboarding, publication modes, channel/group connections, error recovery, IDs, revisions, media, buttons, consent. It also explicitly distinguishes itself from the sibling get_formatting_capabilities, so an agent can separate the two without opening either schema.

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

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

Gives explicit triggering conditions ("call first for onboarding, publication modes in AI chat/browser/Mini App, connecting channels/groups or error recovery") alongside a named alternative ("Use get_formatting_capabilities for full RichDocument syntax"). It also tells the agent how to pick the right mode: topic plus level=workflows for steps, reference for examples.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds non-obvious context beyond that: the signature is owner-bound, it 'Never publishes,' and documentJson/media must be preserved during a complete replacement — a real behavioral caveat for the subsequent update.

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

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

Three short sentences, each carrying distinct information (when to use, read-before-edit workflow, preservation warning), with the purpose front-loaded. The telegraphic phrasing is efficient but occasionally clipped.

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. Given trivial schema complexity, the description covers the operational essentials — read-only nature, owner binding, no-publish guarantee, and the replacement caveat — leaving only the ID format 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 signatureId parameter is undocumented in the schema. The description only indirectly hints at the value's meaning via 'owner-bound auto-signature,' offering no format, ID-source, or lookup guidance 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 description gives a specific verb ('Read') and resource ('owner-bound auto-signature'), and the opening clause scopes it to 'managing post auto-signatures.' It implicitly distinguishes itself from write siblings like update_signature, but never names them explicitly, so it stops short of a top score.

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

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

It states a clear usage context: 'Read this owner-bound auto-signature before editing it,' which establishes a read-before-write workflow. It does not, however, name alternatives such as list_signatures or preview_signature or state exclusions, so the routing guidance is good 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 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds one useful behavioral fact — results are limited to channels the authorized user can manage — but says nothing about ordering, pagination, or auth requirements 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 efficient sentence with no waste. It is slightly front-loaded with the filler phrase "Use this when you need to" rather than leading with the action, but it remains compact.

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 detail is unnecessary, and the annotations cover the safety profile. For a zero-parameter read tool this is close to complete, with only pagination/ordering behavior left unstated.

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

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

The tool takes zero parameters, so the description has no parameter semantics to explain; the baseline of 4 applies. Nothing in the description misleads about the parameterless signature.

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

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

The description states a specific verb (list) and resource (Telegram channels, groups, and chats) and scopes it to what the authorized user can manage. It is clear, though it does not explicitly differentiate itself from list_publications/list_signatures/list_templates siblings beyond the resource noun.

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 Telegram channels..." gives implied usage context but names no alternatives, no prerequisites, and no when-not-to-use conditions. Adequate but minimal.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered structurally. The description adds useful downstream context — the returned publicationId feeds rescheduling, cancellation, targeted edits or deletion — but says nothing about pagination behavior or result ordering (limit/offset exist).

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

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

Two sentences with zero filler; the usage trigger is front-loaded ahead of the return value. Efficient, though it is arguably too terse given eight largely undocumented parameters.

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

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

An output schema exists, so return-value details are not required, and the description adequately frames the read. But with eight parameters at 13% coverage and no filtering guidance, it falls short of what an agent needs to call this correctly across its three advertised scenarios.

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 13%, leaving to/from/limit/offset/postId/status/channelId undocumented; only sort carries a description. The description gestures at three filters (scheduled, failures, published) but never ties them to the status or date parameters, so it does not compensate for the coverage gap. Baseline 3 for high coverage does not apply here.

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

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

The description names the resource (publications) and its scope — scheduled, failed-delivery, and already-published messages — and states the concrete output ('Returns publicationId'). It is clear enough to distinguish a calendar/listing read from mutating siblings like reschedule_publication, though it never uses an explicit list/read verb.

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 'Use when inspecting scheduled publications, delivery failures or messages previously published' gives explicit trigger scenarios that map to the status filter. However, no alternative or exclusion is named despite dense sibling overlap (get_post, search_posts, show_post_card), so routing 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 declare readOnly, idempotent, non-destructive and closed-world. The description adds genuinely new context: saved content is untrusted data and the tool never publishes, which is useful security framing not derivable from 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 trigger condition. The opening "Use this when managing..." and the following "Use this to find..." overlap slightly, but the untrusted-data warning 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 no explanation, and the annotations carry the safety profile. The description covers what is listed (signatures plus account/channel bindings) and adds the trust caveat, leaving little missing for a zero-arg list tool.

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

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

The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to compensate for. Baseline 4 applies for a parameterless 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 and resource: find reusable post auto-signatures and account/channel bindings. This distinguishes it from single-item siblings like get_signature and mutation siblings like create_signature/assign_signature, though it does not explicitly name them.

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 managing post auto-signatures" sets a broad context and "Use this to find reusable..." implies the discovery use case, but there is no explicit when-not guidance or named alternative (e.g., get_signature for a single signature). Usage is only implied.

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

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

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?

The description adds significant behavioral context beyond annotations: it discloses that it may fetch external image URLs, enables a public preview link, never publishes, and gives instructions for handling truncated or unavailable screenshots. This goes well beyond the readOnlyHint=false and openWorldHint=true annotations.

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

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

The description is dense but front-loaded with the core usage case. Every sentence adds useful information, though it could be slightly more structured.

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

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

Given the presence of an output schema, the description doesn't need to detail return values. It covers all necessary behavioral aspects: preview types, external image fetching, failure handling, and non-publishing nature, making it complete for an agent to invoke 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 50%, and the description compensates by telling how to find draftId via search_post_drafts. It doesn't explain channelId's purpose, which is covered in the schema description, so it adds some but not complete value.

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

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

The description clearly states the tool's purpose: requesting a saved draft screenshot, public browser preview or validation warnings. It specifies what it returns (documentJson/richHtml, JPEG) and distinguishes itself from show_post_card 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?

It explicitly says when to use this tool ('Use this when requesting a saved draft screenshot...') and provides a direct alternative for in-chat cards ('Use show_post_card for an in-chat card'). It also instructs how to find draftId and handle screenshot failures.

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

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

Goes beyond the annotations by disclosing that the call persists share state (a public preview link), may fetch external media, and returns an image plus link intended for display. It also states a negative constraint ('Never sends to Telegram'). This is solid added context, though auth/permission requirements are not 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?

Short and front-loaded, but the opening sentence is filler that restates the domain rather than the action, and 'using display instructions' is opaque platform jargon. The Telegram sentence is useful but placed as an afterthought.

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 not be explained, and the description still signals the image/link result. The persistent share-state side effect is covered, which is the main behavioral risk; permissions and rate limits are the only notable omissions.

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 says nothing about signatureId, so it does not compensate for the schema gap. The parameter name is self-describing as a signature identifier, which keeps this from being a serious hazard, but no constraint or format meaning is added.

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: enabling a public read-only preview link for an auto-signature and returning its JPEG screenshot. This is meaningfully different from get_signature or preview_post, though neither sibling is named explicitly, so differentiation is left partly 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 this when managing post auto-signatures' is broad topic context rather than a use condition; it does not say when to prefer this over get_signature or preview_post. Usage is implied but no alternatives or exclusions are given.

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

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

Annotations declare destructive/idempotent/openWorld, and the description adds genuinely new behavioral context: publication requires captured affirmative authorization, dryRun creates no publication and sends nothing, stale expectedRevision rejects the call, idempotencyKey should be reused on retry, and indeterminate outcomes are not treated as delivered. This goes well beyond what the annotations and schema convey.

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

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

Front-loaded with the when-to-use clause followed by prerequisites, then per-parameter notes and failure semantics. Dense and largely waste-free, though the telegraphic phrasing and repetition of confirmation/dryRun rules that also appear in the schema costs a little efficiency.

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

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

For a destructive, open-world mutation with 7 params and an output schema, it covers the approval workflow, preflight, staleness, retry and the ambiguous-outcome rule, so return values need not be explained. It stops short of stating rate limits, permission requirements, or what a successful publication job looks like downstream (e.g., how it relates to list_publications/cancel_publication).

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 71% and documents most parameters, so baseline is 3; the description adds real meaning on top by explaining that confirmationText must be a verbatim quote of the user's authorization (no magic phrase/language), that expectedRevision guards against stale content, and that idempotencyKey is for retry reuse. It does not add syntax detail for draftId or the channelId title-matching rule beyond the schema.

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

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

States a specific verb+resource+effect: publishing a reviewed draft to a connected channel/group. It implicitly separates itself from schedule_post ('never bypass it with scheduling'), preview_post and list_channels (named as prerequisites), so the agent can distinguish it from the surrounding publication tools without opening their schemas.

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

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

Gives explicit when-to-use (reviewed draft, explicit user approval), names the prerequisite tools to call first (list_channels, preview_post), describes the dryRun alternative path, and states exclusions (do not bypass consent via scheduling; pending/uncertain is not delivered). Nothing about selection 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is structured. The description adds valuable behavioral context beyond annotations: emphasizes it never edits, enables sharing, or publishes, and explains pagination via nextCursor/hasMore and owner-only IDs/snippets. However, it doesn't detail rate limits or auth requirements, leaving a modest gap.

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

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

The description is compact and front-loaded with the primary use case, then flows into constraints and related tools. Some sentences like 'Matches all keywords/fragments in title and rich text, ignoring case' are slightly redundant with the schema but still earn their place for clarity.

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

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

Given the tool has an output schema (so return values needn't be explained) and rich annotations, the description covers all an agent needs: purpose, when to use, alternatives, behavior, and pagination. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so the schema fully documents all three parameters. The description adds only marginal value with 'Empty query lists recent drafts', which is already covered in the query parameter's schema description. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

Names a specific verb and resource ('search_post_drafts' for 'finding an existing draft') and explicitly distinguishes from siblings search_posts and preview_post. An agent can identify the tool's function without opening the schema.

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

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

Explicitly states when to search first ('when draftId is unknown'), what not to do ('do not ask for a link'), and names alternative tools show_post_card and preview_post with their distinct purposes. Complete routing guidance.

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

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

Annotations already 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 already declare readOnly/idiompotent/non-destructive, but the description adds value beyond them: it discloses that this is a UI render surface in MCP Apps hosts, that calling it redundantly duplicates cards, and that it never publishes, schedules, or enables a public link. It does not describe what the rendered card contains or any host-specific failure modes, so it falls short of a 5.

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

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

Four compact sentences, front-loaded with the usage trigger and followed by the anti-pattern, the parameter source, and the side-effect boundary. Every sentence carries distinct information, though the host/browser distinction sentence is slightly compressed and could be tighter.

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 description still covers invocation triggers, the sibling to avoid, how to source the required ID, and the exact non-side-effects. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 0%, so the description must carry the load for the single postId parameter — and it does, telling the agent exactly which tools (search_posts/search_post_drafts) to use to obtain a valid ID. It adds no format/validation detail beyond the schema's length constraints, keeping it at 4 rather than 5.

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 (open/render an existing post card) on a specific resource, and immediately differentiates itself from create_post_draft, preview_post, and get_post by naming the duplicate-card failure mode and the host-rendering behavior. An agent can pick this over its many siblings without opening their schemas.

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

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

Gives explicit when-to-use triggers (author asks to open a card, requests another card, reports a missing card), an explicit when-not-to (after create_post_draft, which already attaches a card), a prerequisite (resolve postId via search_posts/search_post_drafts), and a disambiguation (browser preview link is different). Nothing 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 declare destructiveHint=true and idempotentHint=false, so the mutation/safety profile is covered. The description adds two useful behavioral facts beyond that: the revision-read prerequisite and the snapshot isolation rule (scheduled/sent messages are untouched until apply_post_to_publication). What a change destroys or how revision conflicts resolve is still 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?

Three tight sentences, front-loaded with the use-when trigger, followed by the prerequisite and the routing detail. 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 carry the safety profile. However, for a tool with complex nested button/document parameters and low schema description coverage, the description is thin on how the working-content payload is structured or replaced.

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 29%, so the description should compensate. It names the target fields (title, buttons, attention) but leaves documentJson's full-replace semantics, locale, postId format, and expectedRevision conflict behavior undocumented; "read its revision first" only hints at expectedRevision. The nested schema descriptions for inlineButtons carry most of the load.

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 (a post's working content) and enumerates the mutable fields: content, title, buttons, attention flag. It routes the agent toward apply_post_to_publication for propagation, but never distinguishes itself from the close sibling update_post_draft, leaving some ambiguity about which edit tool applies.

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 changing..." supplies a clear trigger, "Read its revision first" gives a prerequisite, and the closing sentence names the alternative (apply_post_to_publication) for publishing to scheduled/sent messages. It lacks explicit when-not-to-use guidance or a pointer to update_post_draft.

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

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

Annotations already declare destructiveHint=true, non-idempotent and openWorld. The description adds meaningful behavior beyond them: full-replacement semantics ('send full richDocument preserving untouched content; text replaces layout'), that it never publishes, that it returns a JPEG/public preview, and that image references are imported while arbitrary media.src may remain external.

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 front-loaded with the usage guidance and the sentences are compact, but it is dense with jargon ('revision_conflict', 'file slots') and some clauses ('Returns JPEG/public preview; follow display instructions and validation') are telegraphic.

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 return values, and it still covers the main risks (replacement, import, never publishes). For a 16-parameter mutation tool this is close to complete, though a couple of parameters (channelId, templateId, signatureSelection) are left to the schema.

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

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

Schema coverage is 69%, and the description adds real meaning beyond it by explaining the richDocument-vs-text tradeoff ('text replaces layout') and the file-slot binding mechanism ('Bind media.src to file slots'), which links the mediaFile slots to richDocument usage.

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 description establish a specific verb+resource (updating a Postlyra post draft), and the opening clause scopes it to 'legacy draft or binding file slots'. It differentiates itself from the sibling update_post by pointing to that tool for the non-legacy path, though the 'legacy' terminology is not fully explained.

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 ('updating a legacy draft or binding file slots') plus a named alternative workflow ('Prefer get_post -> update_post(expectedRevision); never bypass revision_conflict'). This leaves little ambiguity about when to pick this tool versus its 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?

Adds real semantics beyond the annotations: changes affect future publications only, while queued and published snapshots retain their original signature, and the tool never publishes. This mutation-scope detail is exactly what annotations (readOnlyHint=false, destructiveHint=true) cannot convey. No auth or rate-limit info, so not a 5.

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

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

Four short sentences, front-loaded with the action and immediately followed by the mutation-scope caveat and the prerequisite. The first sentence is mild filler but the rest each earn their 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 no explanation, and annotations plus the description cover the safety/scope profile well. However, for a 12-parameter mutation tool with a complex nested richDocument and media-slot mechanism, the total absence of parameter guidance leaves a real gap.

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

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

With 12 parameters at 58% schema coverage, the description must compensate for undocumented params, and it does not: richDocument, mediaFiles/mediaFile1-6, inlineButtons, language, and even the required signatureId are never mentioned. An agent gets zero guidance on what to pass or how the media slots bind.

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: 'Edit an owner-bound reusable auto-signature,' which clearly separates it from create_signature, delete_signature, assign_signature, and get_signature. The opening frame ('Use this when managing post auto-signatures') is vague but the operative sentence is precise.

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 prerequisite ('Read get_signature first') naming a sibling tool, plus a negative scope statement ('Never publishes') that separates it from publish_post. It does not enumerate alternatives like update_template or convert_draft_to_signature, so not a full 5.

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

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

Annotations already convey that this is a mutation (readOnlyHint=false) and potentially destructive (destructiveHint=true). The description adds a meaningful behavioral boundary: only the author's own templates are editable. It does not go further to explain update semantics (e.g., whether provided fields replace the whole template), but the annotation coverage lowers the burden.

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

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

The description is a single compact sentence that front-loads the action and resource, then states the key limitation. Every word earns its place and there is no redundant restating 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 tool with six parameters, a nested object, and a destructive annotation, the description is thin: it omits any information about what fields mean, whether partial updates are allowed, and what happens to omitted fields. The output schema and annotations fill some gaps, but the lack of parameter guidance leaves the definition only minimally complete.

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

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

Schema description coverage is 0%, so the description bears the responsibility for explaining parameters, but it does not mention templateId, name, locale, category, description, or documentJson at all. The schema property names are somewhat self-explanatory, but the description adds no guidance about which fields are editable or how documentJson relates to the template.

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

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

The description clearly identifies the action ('changing') and the resource ('the author's saved template'), and distinguishes it from related sibling tools by explicitly stating what cannot be edited: system templates and other users' templates. This gives an agent a clear match for the update_template operation.

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

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

The description states when to use the tool ('when changing the author's saved template') and gives an important exclusion: system templates and other users' templates cannot be edited. It does not explicitly name an alternative tool for those excluded cases, but the context is clear enough for an agent to route around them.

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 convey that the tool mutates state (readOnlyHint=false) and is idempotent, so the description does not need to restate those. The added fact that existing publication times are untouched is useful behavioral context beyond the annotations. However, it does not disclose overwrite behavior or whether omitted parameters are preserved.

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

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

Two sentences with no filler: the first states when to use the tool, the second states an important boundary. The key trigger is front-loaded, and every clause earns its place.

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

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

Given the output schema exists and annotations cover the mutation/idempotence profile, the description covers the main decision points: when to use, what it changes, and what it explicitly does not change. It could mention that omitting a parameter leaves that preference untouched, but the optional-parameter schema plus the wording makes this reasonably inferable.

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 low (33%), and the description compensates by mapping each parameter to plain language: time zone, weekly publication target, and content reminder preference. It does not explain cadencePerWeek's 0-70 range, the meaning of 0, or that all parameters are optional independent updates, so it adds some but not full semantic value.

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

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

The description uses a specific verb ('change') and names the exact resources: time zone, weekly publication target, and content reminder preference. It also explicitly distinguishes itself from scheduling tools by stating 'Does not change existing publication times.' An agent can tell what this tool is and is not for.

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

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

The description gives an explicit trigger condition ('Use when the author asks to change...') and a clear exclusion ('Does not change existing publication times'). It does not name alternative sibling tools like reschedule_publication or schedule_post, but the when/when-not guidance is strong enough for an agent to route correctly.

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