PostPen

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

Annotations already mark this as non-readonly, non-destructive, non-idempotent; the description goes further by disclosing that the URL is private, expires in 2 hours, must be consumed via PUT with the returned headers, and enforces per-type size limits. It does not state what happens if you call it twice (idempotency consequence), leaving one behavioral 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?

Front-loaded purpose, then workflow, then expiry, then limits — a natural priority order with no filler. The single paragraph is dense but every sentence carries operational information an agent needs.

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

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

No output schema exists, and the description compensates fully by naming the three returned values (upload_url, the headers, upload_id) and how each is used. Combined with the flow and limits, an agent has everything needed to invoke and consume the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the per-type size limits (image 5MB, mp4 75KB–200MB, PDF 100MB) directly constrain size_bytes and explain why content_type defaults from type. The alt_text mention is about a sibling's parameter rather than this tool's.

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 a private, short-lived upload URL') plus the concrete input cases it handles (carousel PDF, image, mp4) and explicitly distinguishes itself from save_draft by naming save_draft as the downstream consumer. An agent can tell this is the pre-upload URL-minting step, not the media-attaching step.

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

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

Gives the exact when ('a file that has no public HTTPS link'), the end-to-end invocation path (HTTP PUT of raw bytes to upload_url with the returned headers), and the alternative routing ('upload_id is then accepted by save_draft as media: [{ upload_id }]'). Nothing about choosing this vs siblings 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=true, so the deletion risk is covered structurally. The description adds real value on top: it discloses the refusal behavior when confirm is false and the eligibility constraint that only unpublished, unscheduled drafts qualify. Return/shape details are not covered, keeping it from a 5.

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

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

Three short sentences, front-loaded with the operation and its scope, then the confirmation gate, then the exclusion. Every sentence carries distinct information with no filler.

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

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

For a two-parameter destructive tool with no output schema, the description covers eligibility, permanence, and the confirmation precondition — enough to call it safely. It stops short of explaining what happens to the draft afterward or error behavior in more detail, so not a full 5.

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

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

Schema description coverage is 100% and both parameters (id, confirm) are already documented in the schema, including where the id comes from and that confirm must be true. The description restates the confirm requirement in prose but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Permanently deletes an unpublished draft') with an explicit eligibility scope ('is_draft, not scheduled, not sent'). It also carves out what it does not touch ('Scheduled and published posts cannot be deleted'), which distinguishes it from siblings like unschedule_post and save_draft.

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

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

The exclusions ('scheduled and published posts cannot be deleted') give clear guidance on when this tool is not applicable and must be replaced by a sibling. However, it does not name which alternative to use instead (e.g., unschedule_post), leaving that inference to the agent.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's job is to add context — and it does: LinkedIn totals include posts not made through PostPen, the figures are observations not causes, and small numbers move a lot by chance. Those caveats materially affect how an agent should interpret and report results. It does not discuss auth, quotas, or latency.

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 long but front-loads the core metric list before moving to the per-post detail and the caveats, so the important material arrives first. The explanation of 'vs_usual' (1.3 = 30% above usual) is dense but earns its place for a non-obvious custom metric. A couple of clauses could be tightened, but there is little filler.

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

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

There is no output schema, so the description must carry the return contract — and it does, enumerating the account metrics, the percentage change and impressions-per-day derivations, the extra follower fields for personal profiles, and the exact shape of 'recent_posts' including engagement_rate, comment_share, attributes, and the vs_usual normalization. An agent can describe results accurately without guessing.

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

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

With a single parameter and 100% schema description coverage, the schema already documents 'days', its 7-90 bounds, the 30-day default, and the equal-length preceding comparison window. The description restates the same windowing logic ('the last N days next to the equally long period before') without adding syntax or format detail beyond the schema. Baseline 3 applies.

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

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

The description states a concrete verb and resource with unusual specificity: account-level growth metrics (impressions, reach, reactions, comments, reposts) for the last N days versus the preceding equal period, plus per-post 'recent_posts' data. It is unmistakably distinct from a single-post stats tool in substance, though it never names a sibling (e.g. get_post_stats) to make the boundary explicit.

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

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

It gives real usage direction: 'Use it to plan content: compare the change in results with the change in how much was posted, then look at which recent posts beat their account's usual.' That is a clear analytic workflow rather than a bare statement of function. It stops short of naming when not to use it or which alternative to pick.

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

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

With no output schema, the description carries the full burden and does so: it documents the exact returned fields, null semantics ('null when LinkedIn did not return it'), the engagement_rate threshold behavior under 100 impressions, latency ('LinkedIn can lag by a few hours'), lifetime-vs-window scope, and the needs_reconnect permission failure mode with its remedy. This is far beyond the readOnly/openWorld 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?

Front-loaded with the core resource and metrics before the caveats, and nearly every clause carries distinct information. The field inventory is dense but justified given the absence of an output schema; only minor overlap with the schema's id description.

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

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

For a read-only single-post stats tool with no output schema, the description covers return fields, null handling, freshness, permission failures, and eligibility. An agent has everything needed to call it and interpret results correctly.

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

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

Schema coverage is 100% for the single id parameter, so the schema already documents that it must come from list_posts with status sent. The description only restates that constraint by noting that sent posts are the ones with statistics, adding no new syntax or format detail.

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 (reads) and resource (engagement for one published post) and enumerates the exact metrics returned, which cleanly separates it from account-level siblings like get_insights. An agent can distinguish it from every sibling without opening a schema.

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

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

Gives a hard usage precondition ('Only posts with status sent have statistics') and implicitly routes comparative/account analysis to get_insights. It never states an explicit when-not or names get_insights as a formal alternative, so it stops short of full routing guidance.

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

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

Annotations already cover the read-only/non-destructive safety profile, but the description adds platform constraints (LinkedIn only permits company page posts), a return-shape caveat (commenters come back as LinkedIn ids, not names, because the API withholds them), and a prompt-injection warning to treat third-party comment text as data. These are substantive traits not present in the structured fields.

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

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

Three dense sentences, front-loaded with what is returned and then the constraint and the safety note. Every sentence carries information, though the final sentence is packed with two distinct ideas (platform restriction and alternative tool) that could be cleaner split.

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

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

With no output schema, the description compensates by enumerating the returned fields (text, time, likes, replies, commenter id) and explaining the id-vs-name limitation. Combined with the usage restriction, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so both 'id' and 'limit' are already fully documented in the schema; the description adds no syntax, format, or default information beyond it. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('lists the comments on one published company page post') plus the exact fields returned, and explicitly contrasts itself with get_post_stats for the comment count. An agent can distinguish it from every sibling without opening a schema.

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

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

Gives an explicit precondition (only company page posts) and an explicit failure case (personal profile post -> supported is false), then names the alternative tool (get_post_stats) for the count use case. Both when-to-use and when-not-to-use are 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?

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), so the description focuses elsewhere and usefully discloses output contents (id, network, type, name), the current single-network limitation, and a security-relevant fact: 'Never returns LinkedIn tokens.' That is real extra context beyond the annotations.

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

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

Three sentences, front-loaded with what the tool does, then output shape, then the key integration fact. The parenthetical 'more networks later' is mild filler but contextually useful for future-proofing; otherwise there is little waste.

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

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

With no output schema, the description must carry return-value semantics, and it does: it enumerates the returned fields, gives the concrete 'personal' id example, and explains how those ids are consumed. Nothing an agent needs to call or interpret this tool is missing.

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

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

There are zero input parameters, so the baseline is 4. The description instead clarifies output-parameter semantics, explaining the meaning and downstream use of the returned destination ids — more than the empty schema provides.

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

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

States a specific verb (lists) and resource (destinations this account may post to), and clarifies scope relative to siblings by noting the ids are the values the destination parameter of the other tools accepts. An agent can immediately tell this is the read-only lookup that feeds the publish/upload tools, not one of 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?

Implies the use case clearly: call this to discover destination ids before invoking the posting tools that take a destination parameter. It gives solid context but never explicitly says 'call this before publish_now/schedule_post' or states any exclusion, so it stops short of full 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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description goes well beyond that by disclosing the shape and null semantics of each returned row (media_alt_text alignment with media_urls, created_via nullability, preview_url), which is valuable given there is no output schema. It does not mention ordering, rate limits, or auth requirements, 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?

Purpose is front-loaded in the first clause, which is good, but the remainder is a single dense run-on sentence with deeply nested parentheticals that is hard to scan. The field detail earns its place as an output-schema substitute, but the total lack of structural breaks hurts 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 no output schema, the description carries the return-value burden and does so thoroughly, documenting each row field and its null conditions. It omits ordering guarantees, pagination behavior beyond the limit default, and total-count information, which keeps it short of complete.

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

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

Schema description coverage is 100%, so both limit and status are fully documented in the schema and the baseline is 3. The description's restatement of the queue names adds marginal mapping value but no syntax or default information beyond what the schema already provides.

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

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

States a specific verb (lists) and resource (this account's posts) scoped to three named queues — drafts, scheduled, sent — which map directly to the status enum. An agent can distinguish this from list_comments or list_destinations 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?

The description names the three queues but never says when to choose this tool over alternatives such as get_post_stats or get_insights, nor does it state any prerequisite or exclusion. Usage is only implied by the status enum in the schema.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the risk profile is covered; the description adds meaningful behavioral detail on top – the confirm gate, that draft media and its alt text are carried along, and the like-for-like behavior with schedule_post for destination persistence. It stops short of saying the publish is irreversible or describing 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?

Four compact sentences, front-loaded with the action, then the confirm gate, then destination routing, then the media exclusion. No filler or redundancy; each sentence carries a distinct constraint.

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

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

With no output schema, the description still covers the side effects that matter (media/alt text published, confirm required, destination resolution). It omits what is returned on success/failure and whether the action can be undone, though destructiveHint partially compensates.

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

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

Schema description coverage is 100%, and the schema's destination description already spells out the personal/company URN semantics in far more detail than the description does. The description's 'optional' framing adds mild routing value but largely restates structured data, so the baseline 3 applies.

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

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

States a specific verb+resource ('publishes a saved post to LinkedIn') plus timing ('immediately'), which cleanly separates it from the sibling schedule_post. It also pins the input source ('stored on the draft by save_draft'), so an agent knows which object id to supply.

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 hard prerequisite ('Refused unless confirm is true') and an explicit exclusion ('Media is not accepted here'), plus routes destination lookup to list_destinations. It never explicitly names schedule_post as the alternative for deferred publishing, but the contrast is strongly implied by 'immediately'.

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

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

With destructiveHint=true already declared, the description goes well beyond the annotation: it discloses that on update 'omitting media keeps existing attachments and their alt text, and media: [] removes them,' that schedule time and destination are preserved, that media_alt_text cannot be combined with media, that people (only company pages) can be tagged, and that the result carries a preview_url meant to be shown to the user. These are exactly the destructive/stateful behaviors an agent needs and are 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?

Front-loaded with the create/update distinction, and every sentence carries real semantics about a behavior or constraint. The cost is structure: it is delivered as one dense block rather than being broken into purpose/update/media/alt-text sections, which makes an 8-parameter tool harder to scan.

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

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

For a mutation tool with no output schema, the description covers create vs update, media sourcing and removal semantics, mentions constraints, alt-text lifecycle, destination selection, and even names the result field (preview_url). Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not carry: 'content is required to create; an update takes content and/or media,' the create-vs-update requirement shape, the mutual exclusion of media and media_alt_text, and the image-only constraint on alt_text. It mostly restates per-field rules already in the schema, hence 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?

The opening states a specific verb and resource ('Saves LinkedIn post text ... as a draft, or updates an existing unpublished post') and immediately disambiguates the two modes: 'Without id it creates a draft. With id it updates a draft or a scheduled post that has not been sent.' It also implicitly separates itself from publishing siblings by stressing 'nothing is sent to LinkedIn,' so an agent can distinguish it from schedule_post/publish_now without opening a schema.

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

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

It gives clear selection context (omit id to create, supply id to update; content required to create, content and/or media on update) and points at the related tools create_upload (large files), list_destinations (destination ids) and list_posts (media_urls order). It doesn't state an explicit when-not versus schedule_post/publish_now beyond the note that first_comment and auto_react are applied at publish time by those tools, so the routing is strong but inferred rather than spelled out.

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

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

Annotations declare non-readonly, non-destructive, open-world, so the safety profile is covered. The description adds real context beyond that: the timestamp must be in the future with a timezone, media is not accepted here, alt text is published with stored images, and the result carries preview_url that is meant to be shown to the user. No auth or rate-limit detail, and no failure modes beyond the alt-text refusal documented in the schema.

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

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

Four dense sentences, front-loaded with the core action and constraint before secondary details. Efficient overall, though the future-ISO-8601 phrasing and alt-text ordering restate the schema, which slightly dilutes density.

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

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

For a 4-parameter tool with no output schema, the description covers the prerequisite, the routing to list_destinations, the media restriction, and the meaningful return value (preview_url to surface to the user). Missing only edge-case behavior such as scheduling failures or overwriting an existing schedule.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces destination semantics (personal profile vs company page) and the ordering of media_alt_text, but most of that content is duplicated in the schema, so it adds little beyond the structured fields.

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

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

States a specific verb+resource ("Schedules a saved draft") and immediately distinguishes itself from the sibling save_draft by naming the prerequisite relationship. Combined with the sibling set (publish_now, unschedule_post), an agent can tell exactly what this tool does 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?

Clear context: it operates on a draft from save_draft, takes a destination from list_destinations, and explicitly excludes media upload ("Media is not accepted here"). It stops short of stating when to choose this over publish_now or unschedule_post, but the prerequisite and routing references give strong implied 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 destructiveHint=true, readOnlyHint=false, openWorldHint=false and idempotentHint=false, and the description does not contradict them. It adds genuinely useful context beyond them: the state transition (scheduled → draft), that content survives, no LinkedIn side-effect, and the confirm gate. It never addresses re-invocation behavior, which matters given 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?

Four short sentences, front-loaded with the action and its effect, then constraints. Every clause carries information; the PostPen calendar analogy is the only slightly decorative element, but it usefully concretizes 'move to draft'.

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 mutation with no output schema and full annotation coverage, the description supplies the state transition, refusal condition, and the published-post restriction an agent needs. The only gap is behavior on repeat invocation, which the non-idempotent annotation flags but the description leaves unexplained.

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

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

Schema description coverage is 100% and both params are documented there, including that id comes from list_posts status scheduled. The description restates the confirm requirement ('Refused unless confirm is true') but adds no syntax or edge-case detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('moves a scheduled post ... back to Drafts') plus the exact effect ('clears its schedule time'), and explicitly carves out what it is not ('does not delete the post', 'does not call LinkedIn'). The calendar analogy pins down the semantics, so an agent can separate it from delete_draft and schedule_post without opening a schema.

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

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

Gives clear preconditions: 'Refused unless confirm is true' and 'Published posts cannot be unscheduled', which tells the agent when the call will fail. It stops short of naming an alternative tool (e.g. delete_draft or publish_now) or describing what to do when the post is already published, so it falls below the explicit when-not/alternatives bar.

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