Postey

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

Annotations already declare non-read-only, non-destructive, idempotent and closed-world, but the description adds granularity the annotation cannot: idempotency is scoped to (post_id, tag), and a WRITE-level account permission is required. It stops short of saying what happens when the tag name does not already exist under the account (created implicitly vs. error), which is the one behavior an agent might trip on.

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, zero waste: action first, routing rule second, constraints last. Every sentence carries distinct information.

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

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

With an output schema present and annotations covering the safety profile, the description supplies auth requirements, idempotency scope and sibling routing. Only the success/failure behavior for an unknown tag name is missing, which is a minor 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?

Reported schema coverage is 0% at the top level, but the nested schema does describe tag, color enum and post_id. The description adds no parameter-level meaning of its own — notably it leaves the 'account_id must match the post's account_id' constraint and any tag-creation semantics to 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 and resource ('Attach a tag to an existing post') and immediately contrasts with create_post, so the agent can tell it apart from the siblings that also deal with tags (create_post, remove_tag) 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 names the alternative path ('create_post also accepts tags=[...] at creation time') and the condition that selects this tool ('for a post that already exists'). That is a complete when/when-not rule.

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

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

The description adds substantial behavior beyond annotations: it explains that no credential is returned, that the call can fail with URL-elicitation error -32042, that repeat calls are safe, and that credentials are per account rather than per platform. These details materially help an agent handle the OAuth-like flow.

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

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

The purpose is front-loaded and the remaining sentences each add operational detail about errors, reauthorisation, account ambiguity, and setup blockers. The length is justified by the complexity of the connection flow.

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

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

Despite the existing output schema, the description covers the critical edge cases an agent must know: the browser link return path, the -32042 error, repeat-call safety, per-account credential scope, and ambiguous-account behavior. It is complete for a two-parameter, open-world connection 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%, but the description richly explains account_id: it selects the account being fixed, and omitting it triggers fleet-wide behavior with needs_reauth[] and healthy[] when accounts disagree. The platform parameter is less explicitly described, though its enum values make its meaning clear.

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: connect a social account or re-authorise an expired credential. It clearly distinguishes this from simple account listing by explaining the link-returning and reauthorisation flow.

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

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

It gives explicit when-to-use guidance: connect or reconnect, omit account_id for a fleet-wide check, and provide account_id when resolving a specific account. It also explains the ambiguous-account fallback behavior, leaving little inference needed.

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 destructiveHint=true, but the description goes well beyond that: it warns that automatic adaptation can lose intentional formatting, that the mutation is in place on the same post_id, and that synced_platforms creates an ongoing mirror rather than a one-time copy (only valid when source is socials[0]). These are consequences an agent could not infer from the annotation flags 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?

The core purpose and the update_post alternative are front-loaded, and the prerequisite/validation information is dense and useful. The final two sentences re-explain synced_platforms almost identically to the schema description, which is mild duplication, but nothing else is padding.

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 nested-request parameter, an output schema, and rich annotations, the description covers everything an agent needs: preconditions, the difference between one-time conversion and ongoing mirroring, the formatting-loss risk, and the natural follow-up call. Nothing material is left unspecified.

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 nested request object documents post_id, source_platform, target_platforms and synced_platforms thoroughly, including the mirroring rule and the 'must not include the source' constraint. The description largely restates the synced_platforms semantics rather than adding new parameter-level detail, so the baseline of 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 ('Adapt an existing post's content from one platform to one or more others') plus the crucial scoping detail that the update happens in place on the same post_id. It explicitly contrasts itself with update_post for hand-written per-platform content, so an agent can distinguish it from the sibling 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?

Names the exact trigger ('explicit requests to auto-adapt content, e.g. convert this to LinkedIn'), the alternative route (hand-written content goes through update_post), the follow-up tool (validate_post_content), and the preconditions on source/target platforms. The synced_platforms paragraph further states when mirroring applies versus a one-time conversion.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so safety framing is partially covered; the description still adds real context by stating the result is a DRAFT (not published) and that all platforms share one post_id that grouping, scheduling and analytics depend on. The ungroupable-post_id warning is a genuine consequence the annotations cannot express. It stops short of covering retry/idempotency behavior, which is only 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?

Front-loaded with the verb and state, then layers the multi-platform rule, the anti-pattern, the sibling alternatives and the tag hint. Dense but readable; the shared-post_id point is made twice (grouping benefit, then splitting penalty), which is defensible emphasis but costs a little tightness.

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 deeply nested, multi-platform creation tool with an output schema, it covers everything the agent needs to call correctly: account selection, platform field rules via postey://platforms, content limits via validate_post_content/max-length enforcement, multi-platform batching, tags and sibling alternatives. Return values are covered by the output schema, so no gap remains.

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 single top-level 'request' param carries no schema description (0% reported coverage), but the description compensates by explaining account_id provenance and confirmation, the additional_platforms pairing and uniqueness constraint, and inline tag get-or-create with exact casing. It also provides a concrete call example, which the schema cannot.

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 and state ('Create a new DRAFT post'), immediately distinguishing it from publish_draft and update_post. It also explicitly positions it against convert_post_content, add_tag and validate_post_content, so the agent can tell it apart from siblings 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?

Explicit routing rules: use convert_post_content only for auto-adaptation, not multi-platform creation; pass tags inline instead of calling add_tag; read account_id from postey://accounts rather than guessing. It also gives the positive condition (one call per topic across platforms) and the negative consequence of splitting into separate calls.

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?

Far beyond the destructive/idempotent annotations, it explains that trashing stays recoverable for 30 days but still consumes a draft-limit slot, that permanent deletion is irreversible yet frees the slot immediately, that all listings and schedules are purged, and that omitting mode on a client without interactive support causes a refusal rather than a default. This is exactly the behavioral context an agent needs before an irreversible 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?

Front-loaded with the action scope, then consequences, then the mode mechanics in a logical progression. The mode paragraph is dense with semicolons and clauses, but every sentence carries decision-relevant 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?

With an output schema and destructive annotations already present, the description fills the remaining gaps: eligibility, reversibility window, side effects on schedules and listings, and the interactive-confirmation failure mode. Nothing an agent needs to avoid a wrong or destructive call is missing.

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

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

The description adds meaning to mode beyond the schema description by tying each value to consequences (trash vs permanent) and clarifying that passing it acts immediately without a prompt. The post_id URL/share-link resolution is left entirely to the schema, but the schema already covers it well.

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

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

The description opens with a specific verb and resource ('Delete a DRAFT post') and immediately narrows the scope to posts in DRAFT status, which separates it from siblings like publish_draft, unschedule_post, or update_post. An agent can pick this tool 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?

It states the eligibility condition explicitly (only DRAFT posts; published or scheduled cannot be deleted here) and points to restore_post as the recovery path after trashing. It does not name the tool to use instead for published or scheduled posts, which leaves one routing gap for an agent holding the wrong post status.

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 well beyond the annotations: discloses that the call returns a widget rather than uploading, that the assistant never sees file contents, that non-UI clients fail silently with no error, and that uploaded media cannot be deleted. The silent-failure warning is exactly the kind of trait an agent cannot infer from readOnlyHint/destructiveHint/openWorldHint.

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

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

Front-loaded with the verb and outcome, and every sentence carries operational weight (sibling disambiguation, silent failure, immutability). Slightly dense — the sentence about 'a URL built from an id, filename or path points at no stored object' is the one line whose referent is hard to pin down without the output 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?

Covers the failure mode that matters most (no upload on non-UI clients, silently), the lifecycle constraint (cannot be deleted), and the data-flow guarantee (URL only, not contents). Since an output schema exists, the description is not obliged to document return values, and the remaining gap is closed by that 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?

There are zero parameters, so the baseline is 4; the schema (additionalProperties: false, empty properties) matches the description's claim that nothing is passed in. The description could have made explicit that all interaction happens in the rendered widget, but no parameter meaning is missing.

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

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

Opens with a specific verb+resource ('Upload a local file ... to Postey's CDN') and states the concrete outcome (a cdn_url for a post's media). It explicitly distinguishes itself from the sibling upload_media by input type (local file vs. existing public URL), so an agent can route between them 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?

Names the alternative (upload_media) and the exact conditions that select it: clients that cannot render MCP Apps UI, and source_type='url' or 'base64'. It also states the positive condition — files on the user's machine — with no ambiguity left.

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 genuine context beyond that: the resource-equivalence behavior and the fact that the tool will not pick an account for you when multiple exist, plus 'caller can access' implies permission scoping.

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: what is returned, why this tool exists alongside the resource, and how to handle multiple accounts. Nothing is redundant with the 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 shape need not be explained, and the description covers the resource equivalence and selection caveat. It stops just short of noting whether results are account-scoped by auth context or ordered, but nothing essential for calling it is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly signals a no-argument call by describing a full enumeration with no filtering options.

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 resource (every social account the caller can access) plus its connected platforms, which is exactly what distinguishes it from connect_account or get_team_info. An agent knows this is a read-only enumeration of accounts, not a mutation or a team lookup.

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 tells when to use it: clients that cannot read MCP resources, since it mirrors postey://accounts. It also pre-empts a likely failure mode by stating that when several accounts exist, choosing one is the user's call rather than the tool's. No explicit when-not or named sibling alternative, so not 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?

Goes well beyond the annotations: discloses the hard failure mode ('a call without platform fails'), the cross-status scope (draft/scheduled/published), and that the same data is exposed via the postey://posts/{post_id}/comments/{platform} resource. It stops short of describing result ordering, volume, or pagination behavior, and the output schema carries the return shape.

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

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

Front-loads the definition and what it is not, which is the right order. However, the THREADS/TIKTOK/PINTEREST caveat is restated in the description and again in the platform parameter schema, and the resource-equivalence sentence is a trailing footnote rather than core guidance.

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 read tool with rich annotations and an output schema, the description covers identity, scope, prerequisites, failure mode, sibling disambiguation, and a resource alternative. Nothing needed to invoke it correctly is missing.

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

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

Adds real meaning beyond the schema: a concrete example (post_id=123, platform='LINKEDIN'), the joint-requirement rule, and the reason all nine platform enum values are accepted here without implying audience-comment support. The rationale duplicates some of the platform field's own schema text, so it is additive but partly redundant.

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 ('internal team/collaboration comments attached to a post for a platform') and immediately bounds it as notes visible only inside Postey, never published. It explicitly distinguishes itself from the sibling get_platform_comments, so an agent can route correctly 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 positive triggers ('context before a virality review or when the user asks what the team said'), a negative case ('these are not audience comments'), and an explicit non-fallback rule for THREADS/TIKTOK/PINTEREST where no audience-comment provider exists. Both the when and the when-not are named alongside the alternative tool.

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

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

Annotations say readOnlyHint=false on a 'List' tool, which would otherwise look contradictory; the description resolves this by disclosing the side effect precisely: 'If no watch exists, this creates an active manual-reply watch and starts background polling… existing watches are reused' — which also justifies the idempotentHint. It further discloses which platforms yield nothing and why, a behavioral fact not present in any structured field.

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

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

Dense but front-loaded: purpose, then platform constraints, then side effects, then the disambiguation. The supported-platform list is repeated almost verbatim in the schema's `platform` description, which is mild redundancy, but every sentence carries a distinct fact.

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

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

For a tool with a hidden write/polling side effect and a nested request object, the description covers the critical behavioral risk and the output contract, and an output schema exists so return shape needn't be spelled out. The remaining gap is that the `request` envelope itself is never explained, though all its children are documented in schema.

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

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

The top-level `request` wrapper has no description (reported coverage 0%), and the description adds no guidance on page/size/status semantics or on the interaction between `status` and the manual-reply workflow. The nested properties are self-documenting in the schema, so a baseline 3 is right; the only added value is the mention of the returned comment_id.

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

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

States a specific verb and resource ('List real comments left by other people on the published social platform post') and immediately scopes it to a concrete data source (manual_reply_comments). It explicitly disambiguates from the sibling get_internal_comments at the end ('Postey's internal team comments come from get_internal_comments').

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 coverage per platform (served vs. refused) and pre-empts the most likely wrong move: 'get_internal_comments is not a fallback for them, since it returns private team notes.' It also points forward to the downstream tool ('Returns the comment_id that reply_comment needs').

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the data is scoped to a single post on a single platform and is functionally identical to a named MCP resource, which tells the agent this is a pure read with no side effects or cross-post aggregation.

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 compact sentences with zero filler: the first states exactly what is returned and how it is keyed, the second states the fallback condition. Front-loaded and appropriately sized.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety semantics. The only meaningful gap is the unmentioned post_type parameter and the nested 'request' wrapper, which the schema documents but the description does not surface.

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

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

The description reinforces that lookup is keyed on post_id and scoped to one platform, which adds meaning for two of the three nested fields. However, it says nothing about post_type (FEED/REEL/STORY selection) or the fact that params are wrapped in a 'request' object, so it does not compensate for the reported low schema description coverage at the top level.

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 resource ('full text and media of one post on one platform') and the lookup key ('by post_id'). It also names the exact equivalent resource URI, so an agent understands precisely what data it will get and how it maps to the MCP-resource counterpart.

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 names the alternative (the postey://posts/{post_id}/content/{platform} resource) and the condition that selects this tool: 'for clients that cannot read MCP resources.' That is a genuine when-to-use rule, though it offers no guidance relative to content-related siblings such as convert_post_content or validate_post_content.

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 safety needs no restating. The description adds genuine behavioral facts beyond them: results exclude post text, pagination defaults to size=10 with max=100, and the platform constraint is per-call. Return shape is not described, but an output schema exists, so that gap is minor.

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

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

Five tight sentences, front-loaded with what the tool returns, then the exclusion, then the prerequisites and call-cardinality constraint. Every sentence carries information an agent needs to call it correctly; nothing is padding.

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?

Covers the non-obvious pieces for a filtered list tool: required scope, where account_id comes from, that post text is elsewhere, per-platform call cardinality, and page-size limits. The output schema relieves the description of explaining return structure.

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?

Adds meaning the schema cannot: account_id must come from postey://accounts and should never be guessed, and platform is required per call. However it omits the tag_id and page filters entirely, and its status list (DRAFT, SCHEDULED, PUBLISHED) is missing PUBLISHING, which the schema enum includes — an agent reading only the description would not know that state exists.

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 ('List post summaries') plus the mandatory scope: one account and one platform, filtered by status. The status values are named, so an agent can distinguish this from get_post_content or get_platform_comments 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?

Gives concrete triggers ('my posts', 'drafts', picking a post) and an explicit alternative for the case this tool does not serve ('postey://posts/{post_id}/content/{platform} has that'). It also warns that a cross-platform question requires one call per platform, which heads off a common mis-call.

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 readOnly/idempotent, but the description adds what they cannot: the 60-120s async pass with an immediate job_id, the four status values and what each means operationally, why 'lost' happens (worker replaced by a deploy) and the required recovery, and that polling is free while re-running review_post is a paid duplicate write.

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 and nearly every sentence carries distinct information. The final sentence about double-running review_post is really usage guidance that duplicates the expense theme already implied earlier, so it is slightly redundant within the passage.

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 status semantics — exactly the part an agent must branch on. Combined with timing, cost, and failure recovery, nothing needed to invoke or retry 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 reported as 0% for the nested request object, so the description has to carry meaning — and it does: preferred vs fallback semantics for job_id/post_id, mutual exclusivity ('exactly one ... is accepted'), and what post_id resolves to (most recent job for that post). Gains a small deduction only because the type/shape detail lives in the schema, not the prose.

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 ('Collect the result of a review_post run') and immediately binds it to the sibling pair (review_post starts, get_review_status collects). No sibling ambiguity remains after the first two sentences.

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 precedence rules: job_id preferred, post_id fallback when the handle is lost, exactly one accepted. It also names the failure mode to avoid ('calling review_post again for the same post while a job is running runs a second paid pass'), which is a genuine when-not-to-use instruction.

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, and closed-world behavior, so the bar is lower. The description adds useful behavioral context by naming the returned schedule components and the NOT_FOUND condition, though it does not cover auth or permission requirements.

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

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

The description is front-loaded with the core action and scope, then adds error behavior and the sibling alternative. Every sentence contributes useful information without repetition.

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

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

For a one-parameter read-only tool with existing annotations and an output schema, this description is complete: it covers what is retrieved, the scheduled status constraint, the NOT_FOUND case, and how to list all scheduled posts instead.

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 single post_id parameter is reinforced by the requirement that the post be SCHEDULED and by pointing to get_posts(status=SCHEDULED) as the source of the ID. Given low schema description coverage, this is meaningful compensation, though it does not elaborate on the nested request wrapper.

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

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

The description uses a specific verb and resource: retrieve the current schedule for a SCHEDULED post. It also details what is returned (platforms, UTC times, post actions, Auto-DM rules) and distinguishes the tool from get_posts(status=SCHEDULED).

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 clearly states the tool is for a single SCHEDULED post and points to get_posts(status=SCHEDULED) for listing all scheduled posts, plus notes NOT_FOUND when no active schedule exists. It does not explicitly route modification cases to update_schedule or unschedule_post, so it falls short of fully explicit 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?

Goes well beyond the readOnly/idempotent annotations by disclosing that the response contains real member email addresses and by setting an explicit handling expectation for that sensitive data. It also notes the UUID-to-name translation behavior and the equivalence to the postey://teams resource, which is exactly the kind of context annotations cannot 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?

The core purpose and scope are front-loaded in the first sentence, followed by the translation behavior and resource equivalence. The final two sentences on email handling are slightly verbose but earn their place by covering a real privacy concern.

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 the annotations already cover safety. What remains — what the tool does, why it exists versus the resource, and the sensitivity of the returned data — is fully addressed for a one-parameter read 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 single required team_id is already described inline in the schema ('Numeric team_id from postey://teams'), and the description only indirectly reinforces its origin by referencing postey://teams/{team_id}. It adds no format, validation, or sourcing detail beyond what the schema provides, so a baseline score is appropriate.

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

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

States a specific verb and resource ('Full team details') and enumerates exactly what is returned: every member's resolved display name, email, and access level. It also clarifies a distinct secondary function (translating created_by/published_by UUIDs into names), which separates it from the list-oriented sibling get_teams.

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 tells the agent when to prefer this tool over the MCP resource (clients that cannot read resources) and gives context on when member emails are appropriate to use. It stops short of naming a sibling tool alternative or exclusion, so it is clear but not fully comparative.

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 annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds useful context the annotations do not: the result set is scoped to teams the caller owns or belongs to, and the data mirrors the postey://teams resource. Pagination or result-size limits are not mentioned.

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 scope and contents, followed by the resource-equivalence note. Nothing is redundant with 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 and rich annotations, the description only needs to establish scope and the resource fallback, which it does. The only gap is whether the result list is bounded or paginated for callers with many teams.

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 no parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly spends no space on parameter documentation.

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 resource and scope: 'Every team the caller owns or belongs to,' plus the fields returned (team_id, team_name, accounts, permission level). It implicitly separates itself from the sibling get_team_info by making clear this is a list of all teams, though it never names that 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 a clear condition for use: for clients that cannot read MCP resources, use this instead of postey://teams. That is a real routing rule with a named alternative, but it does not address when to prefer this over get_team_info or get_accounts.

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 description needn't restate safety. It goes well beyond them by disclosing the 24-hour retention window, credential-level (not conversation-level) scoping, and the duplicate-on-reupload behavior — the kind of context an agent cannot infer from structured fields. The 'empty list does not mean nothing was uploaded' caveat is a genuinely useful false-negative warning.

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 resource and returned fields, then the exclusions, then scoping — a logical order with no filler sentences. It is slightly longer than needed because 'scoped to the calling credential' and 'never lists another user's files' restate the same isolation guarantee.

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

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

Output schema exists, so return-value shape is handled structurally, and the description still contextualizes the fields it mentions. Retention, scope, source-of-write, and the upload_media boundary together cover everything needed to call this correctly or decide against it.

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 no parameters, so parameter semantics are moot and the baseline of 4 applies. The description correctly spends no words re-explaining inputs and instead uses the space for scoping and retention semantics.

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

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

States a specific verb and resource (list files uploaded through the file_manager widget) and enumerates the returned fields (cdn_url, name, size, content type), so the agent knows exactly what comes back. It also names the sibling it is distinct from (upload_media), removing ambiguity.

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 it does not list media uploaded with upload_media and that a cdn_url returned by upload_media cannot be recovered here — a clear when-not-to-use rule tied to a named alternative. It also notes that re-uploading creates a duplicate rather than updating, which tells the agent not to expect dedup behavior.

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 well beyond the destructiveHint/openWorldHint annotations by stating the effect is irreversible and publicly visible on real networks, and adds a hard procedural requirement — explicit user confirmation in the current turn — that the annotations cannot express. It also discloses the rejection behavior for non-DRAFT posts.

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: action first, consequences and confirmation requirement second, lookup alternative last. No filler, and the most decision-relevant fact (irreversibility) is placed early.

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 description covers safety, preconditions, and the confirmation gate. The one gap is retry/idempotency behavior, which matters for an irreversible action but is left entirely to the schema's idempotency_key field.

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 on the top-level parameter is 0%, but the nested request properties are extensively self-documented (post_id, platforms, idempotency_key binding rules, natural_posting). The description only echoes 'selected platforms'; it adds nothing about retry keys or platform-subset constraints, so 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 ('Immediately publish a DRAFT post to selected platforms') and distinguishes itself from read-side siblings by naming get_posts(status=DRAFT) as the listing tool. An agent can tell exactly what this does 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?

Gives a clear precondition (post must be DRAFT, non-DRAFT is rejected) and routes to the correct sibling for finding drafts. It does not mention how this relates to schedule_post or review_post, which an agent choosing among publishing paths might also consider.

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 genuinely non-obvious behavior: it returns metadata only and 'never the file's bytes', preventing an agent from expecting a download. It doesn't cover error behavior for a missing/invalid id, which keeps 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, each earning its place: what is returned, when to use it, and the critical 'metadata only' caveat. The most important constraint is front-loaded in the returned-field list and reinforced at the end.

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 value documentation is not strictly required, yet the description still enumerates the key fields. The one real gap is the id-versus-name ambiguity, which matters for a tool whose only parameter is required.

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 all parameter meaning—and it introduces a mismatch: the sole required parameter is named 'name' in the schema, while the description says the file is looked up 'by id'. An agent cannot tell whether to pass a file name or a file id, or what format either takes.

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 ('Return the metadata') and resource ('one uploaded file by id'), names the exact fields returned (cdn_url, name, size, content type), and explicitly distinguishes itself from list_files. An agent can tell what this does 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?

It gives a concrete use case—'Recovers the cdn_url for a file listed by list_files'—which tells the agent when to reach for this tool and which sibling precedes it. It stops short of stating exclusions (e.g., that it should not be used to fetch file bytes versus download_media), so it's clear context rather than 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?

Goes well past the annotations: discloses that only the association is removed, that a no-op returns success (concretizing idempotentHint), that a nonexistent or cross-account tag_id is an error, and that WRITE-level access is required. This is exactly the mutation-safety context 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?

Four compact sentences, each carrying a distinct fact (scope, non-destruction, idempotency, error/auth semantics). The key constraint is front-loaded 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?

Given a mutation tool with annotations, a fully described nested schema, and an output schema, the description covers everything else an agent needs: what is and isn't destroyed, success semantics for no-ops, error cases, 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?

The nested schema already documents tag_id, post_id, and account_id, and the description adds meaning beyond that by stating the cross-account error condition and that the tag entity survives. It does not clarify the request wrapper or the relationship between account_id and post ownership in more detail, so not a 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?

Specific verb plus resource: 'Detach a tag from an existing post by tag_id', immediately distinguishing it from add_tag and from any tag-deletion tool by clarifying the tag itself is not deleted. An agent knows exactly what this operation does.

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

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

The description gives clear conditions for use (you have a post and a tag_id association to break) and explicitly frames the no-op case, so the agent knows what happens when the association is already absent. It never names add_tag as the inverse alternative, so 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 declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is known; the description adds real value by stating that the reply is published directly on the platform and the comment is marked 'replied', making the irreversible external effect and the one-shot limit concrete. It doesn't discuss failure modes or per-platform constraints, and leaves idempotency handling entirely to 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 tight sentences, front-loaded with what the tool does and the effect it has, then prerequisites and platform scope. No filler; slight crowding of platform list and routing note in the middle, but nothing that would be cut without losing information.

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

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

For a destructive, open-world write tool, the description covers the effect, the one-reply-per-comment limit, the prerequisite lookup tool, and platform scope, and an output schema exists so return values need no explanation. Missing only edge-case behavior (failure handling, text limits), which is minor given the annotation and schema coverage.

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?

Top-level schema coverage is 0% (only a single nested 'request' object with no description), so the description carries more burden; it does explain where comment_id comes from and that it is single-use. However, reply_text semantics (per-platform length or formatting limits) are not elaborated, and the idempotency_key is only documented in the schema, not in the 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+resource ("Post a reply to a real audience comment") and pins the exact object it operates on (the manual-reply status-check table, manual_reply_comments). It also separates itself from get_internal_comments, which surfaces a different class of comment, so an agent can distinguish it from siblings 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?

Gives a prerequisite (comment_id must come from get_platform_comments), a hard constraint (each comment can be replied to once), a supported-platform list, and a routing hint that internal team comments belong to get_internal_comments. That is explicit when-to-use, when-not-to-use, and the alternative source.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond them: the accepted input universe is restricted to Postey-owned links, and the tool returns metadata only, not post text. The trailing 'Read-only' mostly restates the annotation, which keeps this 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 dense sentences, front-loaded with what it does and immediately followed by the 'only lookup' scoping rule and the accepted-input restriction. No filler, though 'Read-only' duplicates the annotation and could be dropped without loss.

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 lookup with an output schema present, the description covers everything an agent needs: accepted input forms, what comes back, what does not come back, and the out-of-scope URL types. No further explanation of return values is required since the output schema defines them.

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

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

Top-level schema coverage is 0% (the wrapper 'request' object is undocumented), so the description has to carry weight, and it does: it names the accepted forms (app.postey.ai/?d=..., share URL, raw share_id). That said, the nested share_link field already enumerates the same accepted formats, so the added meaning is mostly the extra URL example and the negative constraint on non-Postey URLs.

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 (Resolve) and a specific resource (Postey share URL or share_id), and names the exact output shape (post_id, account, platform, status). It distinguishes itself from content-fetching siblings by declaring 'Metadata only' and pointing at the content path instead.

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 strong context: 'the only lookup available when a share link is all there is', plus an explicit negative boundary (not Instagram, YouTube, TikTok, X or other social URLs) that prevents a whole class of misuse. The alternative for the actual text is described only as a URI pattern rather than by the sibling tool name (e.g. get_post_content), so the routing is one inference short of fully 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?

Goes well beyond the annotations: it discloses the 30-day recovery window, that content is preserved rather than regenerated, and the state transition to DRAFT for scheduled/publishing posts (with the reason: schedules were purged). This is exactly the side-effect context the annotations (readOnlyHint=false, destructiveHint=false) do not carry.

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 core action, then escalation to behavior, then limits, then the state-transition edge case. No filler and no repetition of the 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?

With an output schema present, return values need no explanation, and the recovery window plus state-transition behavior cover the main risks. Gaps: no mention of permissions/auth requirements, what error a second restore of the same post yields (relevant given idempotentHint=false), and no routing to the batch sibling.

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

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

Only one parameter, and the schema itself documents post_id thoroughly ('Numeric post_id of a post currently in the trash...'). The description adds no format, source, or validation details about post_id beyond the implicit 'a post', so it neither compensates for the reported coverage gap nor adds new meaning.

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 ('Bring a post back from the trash') and clarifies a semantic point agents would otherwise get wrong: it recovers the original object rather than creating a replacement. It does not, however, distinguish itself from the sibling 'restore_posts', leaving the singular/plural split for the agent to infer.

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

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

Gives concrete preconditions: only valid within 30 days of deletion, and it explains the resulting state for SCHEDULED/PUBLISHING posts. Missing is an explicit exclusion pointing to 'restore_posts' for batch restores or 'get_posts' to locate a trashed post_id.

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 well beyond annotations: states posts return as DRAFT, the 30-day recovery limit, that partial success is normal, and that the result reports per-post reasons for failures. These are non-obvious behaviors for a mutation tool that annotations (which only flag readOnly=false, idempotent=false) do not 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-loads what the tool does, then layers constraints, failure semantics, and the sibling alternative in tight sentences. No filler; every sentence carries a distinct fact.

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 needn't be spelled out; the description still summarizes the result shape (names restored posts and per-post failure reasons). For a nested-parameter mutation tool, this is complete enough 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 already 100%, and the description reinforces the key parameter semantics by tying post_ids to the trash resource and noting the 50-item cap matches one page. This adds source-of-truth guidance beyond the schema without contradicting 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?

States a specific verb (restore) and resource (several trashed posts), plus scope ('at once') that separates it from the singular restore_post sibling. An agent can tell the two apart 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?

Names the alternative explicitly ('restore_post handles a single post') and gives the operative condition (bulk restore, 30-day window). Points to postey://accounts/{account_id}/trash as the source of valid IDs, so the agent knows the prerequisite.

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 substantial behavior beyond annotations: comments are internal-only, the call returns a job_id immediately, the AI pass takes 60–120 seconds in the background, duplicate in-flight calls cost extra, and COMMENT-level access is required.

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

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

The purpose is front-loaded, and each sentence adds operational detail: status coverage, async return, result retrieval, duplicate-call cost, and access requirement. There is no empty 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?

Given the async mutation, output schema, and access requirement, the description gives an agent everything needed to call it correctly: when to call, what it returns, how to retrieve the result, and the main cost/retry hazard.

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

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

The description clarifies that the target is a post and that the call returns a job_id, but it does not explain the platform choice or the idempotency_key. The nested schema does document those fields, so this is adequate but not enriched much beyond structured data.

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

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

The description states a specific action and resource: analyse a post for virality and add internal team comments with improvement suggestions. It also distinguishes the async workflow from the sibling status tool by naming get_review_status(job_id).

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 the tool works on drafts, scheduled, or published posts, explains that get_review_status is the read-only way to fetch results, and warns against duplicate concurrent calls because they run another AI pass and are charged again.

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=true and openWorld=true, and the description goes well beyond them: publication is irreversible and publicly visible, confirmation must be explicit, and rejection behavior for stale times is spelled out. It also anchors time computation to server now (retrieved_at), which is genuinely non-obvious operational context.

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

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

Purpose is front-loaded in the first sentence, then each subsequent sentence adds a distinct rule (staggering, irreversibility, confirmation, time arithmetic, rejection). No sentence merely restates the name, title, 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?

For a destructive, open-world mutation with an output schema, the description covers the risky parts: confirmation, irreversibility, and timestamp computation. It leaves open whether platform_schedules replaces or merges with existing entries and what happens if some platforms fail while others publish.

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?

Top-level coverage is 0%, but the description compensates with semantics the nested schema does not state: scheduled_at is UTC, ≥10 minutes ahead, measured from server now, and computed post-confirmation. It adds nothing about natural_posting or timezone, though those properties are already richly documented inline in 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?

Specific verb+resource+precondition: "Schedule a DRAFT post for automatic publication," which implicitly rules out non-DRAFT posts and distinguishes it from publish_draft. It never names sibling tools such as update_schedule or unschedule_post, so the create-vs-modify boundary is left 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?

Gives strong operative rules: scheduling requires the user's explicit confirmation, the timestamp must be computed after that confirmation, relative phrasings need a 15-minute margin, and a past time is rejected rather than moved. It stops short of routing the agent to alternatives (update_schedule for an existing schedule, unschedule_post to cancel), which is the main missing piece.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: uploads consume the caller's storage quota, bytes land on a CDN, and the call bypasses the widget that normally supplies the argument. It stops short of describing failure modes or quota exhaustion behavior, 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 do-not-use warning and the mechanism are front-loaded in the first sentence, and the follow-up sentence routes the agent to the correct tools. No filler sentences.

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

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

Output schema exists so return values need no explanation, annotations cover the safety profile, and params are fully documented in schema. The description supplies the one thing structured data cannot: this is an internal endpoint the agent should route around.

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% and the nested items document data, name, size, and type with fallback behavior for blank names. The description only restates that the payload is base64-encoded, which the schema already declares via contentEncoding, so it adds little beyond baseline.

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 concrete verb and resource ('stores them on Postey's CDN under the caller's storage quota') and immediately frames the tool as an internal widget endpoint, which separates it cleanly from file_manager and upload_media.

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 'Not for direct model use', then names both alternatives and the conditions that select them (file_manager for the drop widget, upload_media for public URL or base64). It also warns that calling it directly bypasses the widget that produces its argument.

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 its annotations, it discloses that removing all platforms reverts the post to DRAFT, that post actions like auto-retweet are deleted, that the action is not reversible, and that it needs the user's explicit confirmation. This is exactly the operational context an agent needs before causing destruction.

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 destructive action, then side-effects, then prerequisites, then edge-case behavior. 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?

The annotations declare a destructive, idempotent, closed-world mutation, the output schema covers return values, and the description supplies the missing pieces: side effects, reverting behavior, and the confirmation requirement.

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

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

The schema documents both nested parameters, and the description adds meaning by noting that passing every scheduled platform removes them all at once, and that only SCHEDULED posts can be unscheduled. It does not say whether an empty array is rejected or what the response looks like, but the core semantics are reinforced.

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 definition uses a specific verb+resource pair ('Cancel the schedule ... on a SCHEDULED post') and names the fields affected (platforms). It also tells the agent apart from the read-oriented siblings 'get_schedule' and 'update_schedule' by explicitly stating what happens to the post.

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

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

The definition gives clear preconditions: only SCHEDULED posts can be unscheduled, explicit user confirmation is needed, and it names 'get_schedule' as the tool that shows currently scheduled platforms. It does not explicitly say when to prefer it over 'update_schedule', which is an alternate mutation of the same resource.

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 well beyond the annotations by explaining that partial updates are safe, omitted fields are carried over, text-only updates do not strip media, media_urls=[] clears media, and a PUBLISHED post is not re-published. It also discloses the two structural exceptions (YOUTUBE and PINTEREST require exactly one content item with a mandatory title), which is precisely the kind of behavior an agent would otherwise get wrong.

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 safety/overwrite semantics are front-loaded and earn their place, but the middle section degenerates into a long enumeration of individual platform config field names that reads as a schema dump and is hard to scan. The PINTEREST paragraph also largely restates the YOUTUBE pattern instead of compressing it.

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

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

Given nested objects, nine platforms, and destructive semantics, the description covers the risky cases (partial update, media removal, single-item YouTube/Pinterest) well, and the output schema covers returns. It omits tags_to_remove behavior and says nothing about what happens when an update targets an ineligible state, but the core is covered.

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?

Adds meaning not present in the schema: which fields are carried over vs. reset, that update_tags takes specs rather than tag_ids, that an existing tag name resolves instead of duplicating, and that contents[0].text means the video/Pin description on YOUTUBE/PINTEREST. These are semantic rules that materially change how the nested params must be filled.

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

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

Opens with a specific verb and resource ('Overwrite an existing post's contents') and explicitly contrasts read vs write by naming get_post_content. It does not distinguish itself from create_post, publish_draft, or schedule_post, which are the closest write-side siblings an agent could confuse it with.

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

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

Gives concrete usage context: applies to DRAFT and SCHEDULED posts, does not re-publish PUBLISHED ones, and points to get_post_content for confirming current state before writing. No explicit 'do not use this when...' routing to create_post or publish_draft, so the routing is implied rather than complete.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds materially new behavior: publication is irreversible and public once the time arrives, Auto-DM rules survive unscheduling, platforms are added/removed by list diffing, and a passed confirmed time is rejected rather than silently moved.

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

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

Dense but front-loaded: the core action and the confirmation requirement come first, followed by timing rules and then platform-set semantics. A few sentences (the relative-vs-absolute margin rule) are layered and require a second read, but none are 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?

Given destructive writes, nested platform entries and an available output schema, the description covers the preconditions, timing constraints, rejection behavior and platform diffing an agent needs. Return values can be left to the output schema.

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

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

The nested schema already documents scheduled_at and timezone well, so the description's added value is operational: the UTC basis (server now via retrieved_at), the 10-minute floor, the 15-minute margin for relative requests, and exact sending of confirmed absolute times. It does not cover natural_posting or timezone behavior, leaving some schema-documented fields without narrative.

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 ('Update the scheduled time and/or platform set for a SCHEDULED post') and scopes it to posts already in SCHEDULED status. It is clearly separable from schedule_post, unschedule_post and get_schedule, which it names.

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

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

Explicitly routes the agent: use unschedule_post to cancel all platforms, get_schedule to inspect current state, and a non-empty platform_schedules is mandatory here. It also states the precondition of explicit user confirmation and that a replacement time is the user's choice, not the tool's.

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, the description discloses important behavioral traits: uploads cannot be deleted through this server, list_files does not show upload_media results, the cdn_url must be used exactly as returned, and local_path requires PosteySkills plus either OAuth or API-key auth. It also describes size limits, chunked uploads, per-platform validation, and storage quota constraints.

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

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

The description is front-loaded with purpose and workflow, then organized by source type in scannable bullets. It is somewhat repetitive because source-type details appear both in the bullet list and in the source_type parameter discussion, but the length is justified by the tool's multiple upload modes and environment constraints.

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 complexity of three source modes, local vs hosted execution, auth requirements, size limits, and the lack of a delete path, the description is thorough. An output schema exists, so return values need not be re-explained, and the description still covers the critical integration context for create_post/update_post.

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

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

The description adds substantial meaning beyond the schema by explaining the tradeoffs and constraints of the source_type enum values, including environment availability and size caps. It does not cover every nested parameter (e.g., content_type and enable_conversion are left to the schema), but its parameter guidance is otherwise strong.

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 ('Upload media') and immediately clarifies the workflow: it returns CDN URLs consumed by create_post/update_post and must happen before the post is created. It also distinguishes this tool from file_manager and list_files by explaining that upload_media outputs are not visible in the file manager index.

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

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

It gives explicit source-type selection guidance: 'url' is preferred on the hosted server, 'base64' is for small files, and 'local_path' is local CLI only with PosteySkills installed. It also names concrete alternatives for larger files ('file_manager upload widget or PosteySkills') and states when each mode is not available.

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, but the description still adds real value: it spells out the two issue categories (hard_limit vs style) and the exact semantics of `valid` being false when either is present. That is behavior an agent could not infer 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?

Four sentences, front-loaded with the operation and its scope, then the routing advice, then the issuing semantics. No filler and no restatement of the tool name.

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?

Covers what is validated, that state is not mutated, when to call it, the account_id dependency, and how to interpret the two issue kinds. With an output schema present, the description does not need to enumerate return fields and correctly doesn't.

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 top-level schema has a single `request` object, but its nested properties carry extensive per-field descriptions, so the schema does most of the work. The description's only parameter-level contribution is reiterating that account_id is required for X to resolve the premium limit — which the schema already states — so it adds little beyond the baseline.

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 (dry-run validate) and resource (post content) plus the exact rule families checked: hard limits, counting rules, threading, banned words, media constraints. An agent can distinguish this from create_post/update_post immediately.

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

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

Explicitly routes the agent: "Useful before create_post / update_post for any non-trivial content" names the sibling alternatives and the condition that selects this tool. It does not state when to skip validation (e.g. trivial single-line posts), which is the only gap.

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