Postly MCP

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

Beyond annotations (destructiveHint=true), the description adds important behavioral details: server uploads files, scheduling capabilities, and multi-platform handling. It does not contradict annotations, and the added context aids agent reasoning.

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

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

The description is a single paragraph that front-loads the primary purpose and covers key points efficiently. While it could be more structured (e.g., bullet points), it is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (26 params, multi-platform logic), the description covers major workflows: media file handling, scheduling, multi-platform steps, and edge cases like blocked platforms. The output schema handles return value documentation.

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 high (81%), but the description adds value by explaining when to use media_file vs media, and that email_subject is required for email targets. This context helps agents choose parameters correctly beyond what schema alone provides.

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

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

The description clearly states the tool's purpose: 'create, queue, or schedule a Postly post through the publishing pipeline'. It distinguishes itself from sibling tools like postly_update_post or postly_upload_media by explicitly mentioning the creation pipeline and file upload integration.

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

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

The description provides explicit guidance on when to use ('Use this when...'), steps for multi-platform posts (e.g., resolve targets, call postly_get_channel_schema), and handling blocked platforms. It does not explicitly state when not to use it, but the context is clear.

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

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

Annotations already mark destructiveHint=true, but the description adds critical behavioral context: requiring explicit user confirmation. This goes beyond annotation data without contradicting it.

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?

Single sentence, front-loaded with purpose and usage condition. Every word earns its place; no fluff.

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

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

For a simple tool with one required parameter, an output schema, and clear annotations, the description fully covers what an agent needs: purpose, when to use (with confirmation), and no missing details.

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

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

Schema coverage is 100% with a clear description of post_id. The tool description does not add extra detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool deletes an existing Postly post, distinguishing it from siblings which are all non-delete operations. The verb 'delete' and resource 'Postly post' are explicit.

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

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

The description specifies 'after explicit user confirmation', providing clear usage context. While it doesn't explicitly name alternatives, siblings are all non-delete, making the guidance sufficient.

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. The description adds no new behavioral traits beyond stating it fetches analytics, which is consistent. No additional context on rate limits, errors, or side effects.

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 concise sentences: first states purpose, second provides actionable guidance. No wasted words, front-loaded with key 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, return values are covered. The description addresses source selection and prerequisite. It could mention supported analytics types, but overall sufficient 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?

Input schema has 100% coverage with detailed descriptions. The description adds minimal semantic value, only linking to list_analytics_sources for obtaining platform and channel_id. The schema already covers the rest.

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

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

The description clearly states the tool fetches analytics for connected sources like Instagram, Facebook, etc. It uses a specific verb-resource pair. However, it does not explicitly differentiate from sibling tool postly_get_post_analytics, which may cause confusion.

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

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

The description provides explicit guidance to call postly_list_analytics_sources if no source is named, helping the agent choose the correct prerequisite. It lacks alternatives or when not to use, but the context is specific enough.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds context about the output (rules, limits, settings) and behavioral advice on defaulting, without contradicting annotations.

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

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

Two concise sentences, front-loaded with purpose, and no wasted words.

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

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

Given the presence of an output schema, the description adequately covers purpose and usage. Minor missing detail on error handling, but overall complete for the tool's simplicity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add further detail about the platform parameter beyond what the schema provides.

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

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

The description explicitly states the tool retrieves platform rules, limits, and settings for social channels, distinguishing it from sibling tools like postly_create_post or postly_validate_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 description clearly states to use the tool before creating or scheduling content, and provides guidance on minimizing user friction. However, it does not explicitly mention when not to use it or alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Description adds 'sanitized details' but does not elaborate on security, rate limits, or other behavioral traits beyond annotations.

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

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

Single sentence, front-loaded with purpose, no wasted words. Perfectly concise.

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

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

For a simple get tool with 1 parameter and an output schema, the description is sufficient. It provides context on the nature of the returned data ('sanitized') but could further differentiate from postly_get_post_status.

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?

Input schema has 100% coverage with a clear description for post_id. The tool description adds no extra parameter information beyond what the schema provides, so baseline score 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?

Clearly states 'sanitized details for a specific Postly post', with a specific verb ('get') and resource. Distinguishes from siblings like postly_list_posts, postly_get_post_analytics, etc.

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

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

Explicitly states when to use ('when an AI agent needs sanitized details'), providing clear context. Does not explicitly exclude alternative uses, but the intent is clear.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that the post must be 'published' and platform 'supported', but does not disclose potential failure modes or rate limits.

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

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

Two sentences, no fluff, front-loaded purpose, efficient.

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 output schema exists and annotations cover safety, the description adequately informs an agent. Could optionally mention that platform and channel_id come from postly_list_analytics_sources.

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 covers 100% of parameters with descriptions. The description reiterates parameter roles (workspace, post, platform, source) but adds no new semantic detail beyond the prerequisite hint.

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?

Description states 'fetch analytics for a published Postly post on a supported platform' – a clear verb+resource. It distinguishes from siblings like postly_get_account_analytics by specifying post-level analytics, but does not explicitly name alternatives.

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

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

Includes prerequisite instruction 'First identify the workspace, post, platform, and analytics source/channel' but provides no explicit guidance on when not to use this tool or comparisons to siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds that it gets 'current publishing status', but does not elaborate on behavior such as what happens if the post_id is invalid or what the response structure looks like. With annotations covering safety and idempotency, a score of 3 is appropriate.

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

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

The description is a single, front-loaded sentence that directly states when to use the tool. No unnecessary words or details, making it highly efficient and easy to parse.

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

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

Given the tool's simplicity (single parameter, strong annotations, and an output schema), the description is sufficient. It could be improved by mentioning the types of status values returned, but the presence of an output schema likely covers that. Overall, it is complete enough for an AI agent to use correctly.

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

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

The input schema has one required parameter (post_id) with a description in the schema itself. The tool description does not add any additional meaning or context for the parameter. Schema description coverage is 100%, so baseline 3 is used.

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

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

The description clearly states the purpose: getting the current publishing status for a specific Postly post. It uses a specific verb and resource, and implicitly distinguishes from siblings like postly_get_post (which likely returns full post data) and postly_list_posts.

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 includes an explicit use case ('when an AI agent needs the current publishing status'), which is good. However, it does not mention when not to use this tool or explicitly differentiate from alternatives like postly_get_post or postly_get_post_analytics, though the context of siblings makes it clear enough.

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 readOnlyHint annotation, the description reveals that the tool separates actual published delivery receipts from queued/processing posts. This is valuable context for accurate response generation.

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

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

Two short sentences with no filler. The first sets the use case, the second clarifies a critical behavioral nuance. Every word earns its place.

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

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

Given the output schema presence and comprehensive annotations, the description covers all essential context: when to use, what it counts, and a key distinction. No gaps.

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

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

Schema coverage is high (85%), so the description need not repeat parameter details. The description focuses on usage context rather than parameter semantics, which is acceptable but adds minimal additional 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?

The description explicitly states to use the tool for counting published posts in date ranges and queued/processing posts. It clearly distinguishes from sibling list tools like postly_list_posts or postly_list_scheduled_posts.

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

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

Provides explicit when-to-use instructions for user queries about post counts and date ranges. Also includes a behavioral warning not to describe queued posts as published, aiding correct invocation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's role is to add context beyond safety. It explains the result covers accounts, pages, profiles, etc., and specifies workspace scoping, which is useful additional behavioral 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?

The description is two sentences with no superfluous words. The first sentence provides the usage context, the second details the resource and scope. It is front-loaded and efficient.

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

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

For a simple listing tool with two optional parameters and an output schema, the description covers the essential behavior and scope. It could benefit from mentioning that it returns a list, but the output schema presumably fills that 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?

Schema coverage is 100%, so the schema already documents both parameters adequately. The description adds minimal new information about parameters beyond restating the optionality mentioned in the schema, so it only meets the baseline of 3.

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

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

The description uses a specific verb 'list' and resource 'analytics sources', clearly distinguishing it from siblings like postly_get_account_analytics which retrieves analytics data. It also specifies the scope (one workspace or all accessible workspaces), leaving no ambiguity about what the tool 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 provides a clear when-to-use statement: 'when a user asks what analytics are available in Postly'. However, it does not explicitly contrast with sibling tools for analytics data retrieval, missing an opportunity to clarify when not to use this 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 already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds limited behavioral detail. It clarifies that the result depends on the authenticated user or connection grant, but does not discuss error conditions (e.g., authentication failure or empty results), which would be useful given the importance of the tool in the workflow.

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

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

The description is a single, succinct sentence that front-loads the purpose and usage context. Every word earns its place; there is no redundancy or unnecessary detail.

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

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

For a simple zero-parameter list tool with an output schema (present but not shown), the description is complete. It states what the tool returns (organizations) and when to use it (before workspace selection). Annotations cover safety concerns entirely. No additional information is needed.

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

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

With zero parameters, schema coverage is trivially 100%. The description adds no parameter information, but this is acceptable because there are no parameters to document. According to the rubric, 0 parameters yields a baseline of 4.

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

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

The description clearly states the verb 'list' and the resource 'Postly organizations', specifying the scope as 'available to the authenticated user or connection grant'. This directly distinguishes it from the sibling tool 'postly_list_workspaces', which lists workspaces after organizations are selected.

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 explicitly instructs to use this tool 'before choosing a workspace', providing a clear contextual trigger. It implies that this should be the first step in workspace selection, which is strong guidance for the agent.

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

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

Adds context about recency and handling of published status beyond annotations, though could elaborate on pagination or ordering. No contradiction with annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words.

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, annotations cover safety. Description covers essential usage context; minor missing detail on ordering but overall complete for a list tool.

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

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

Schema description coverage is 50%; description adds no further parameter meaning beyond what schema provides. Baseline 3 is appropriate.

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

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

Description clearly states it lists recent Postly posts with optional workspace and status scoping, and distinguishes from sibling tool postly_get_publishing_activity.

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 when to use (need recent posts) and when to prefer alternative (for publish counts), providing a concrete example and reason.

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 and idempotentHint, covering safety and idempotency. The description adds parameter usage context but does not disclose additional behaviors like pagination or rate limits. With annotations, the bar is lower; a 3 is appropriate.

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 concise sentences, each serving a distinct purpose: stating tool purpose, guiding on relative_range, date, and scheduled_from/until. No redundant or vague language; front-loaded with the core trigger scenario.

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 9 parameters, an output schema, and good schema descriptions, the description fills gaps by explaining parameter selection. It does not cover pagination (limit/skip) or workspace filtering in detail, but the schema provides that. Overall complete given the available metadata.

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 significant value beyond the schema by explaining when to use each date-related parameter and giving concrete examples (e.g., 'Use "tomorrow" for requests like...'). Schema coverage is 78%, and the description compensates well for the remaining 22% by clarifying usage semantics.

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

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

The description clearly states the tool is for listing scheduled posts, using phrases like 'posts they have lined up, queued for a future date, scheduled tomorrow'. It distinguishes from sibling tools like postly_list_posts by specifically targeting scheduled content.

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

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

Explicit guidance on when to use each parameter: prefer relative_range for natural language dates, date for exact local day, scheduled_from/scheduled_until for ISO ranges. Also provides example triggers like 'How many posts do I have lined up for tomorrow?'.

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 indicate this is a read-only, idempotent, non-destructive operation. Description adds that it lists specific types of targets (social channels, email/newsletter) but does not elaborate on other behavioral aspects like pagination or response format. With annotations covering safety, a score of 3 is appropriate.

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?

Description is a single, tightly worded sentence that front-loads the purpose and usage context. No unnecessary words or repetition, making it highly concise and efficient.

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

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

For a simple list tool with one parameter and an output schema, the description sufficiently defines when to use it and what it returns. It could mention output details, but the output schema handles that. Overall adequate for effective use.

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 'workspace_id' with a schema description. The tool description does not add additional meaning beyond the schema. Since schema coverage is 100%, baseline score of 3 is justified.

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?

Description explicitly states the tool lists connected social channels or email/newsletter targets for a Postly workspace, clearly indicating the action and resource. The title 'List Publishing Targets' aligns with this purpose, and the description helps distinguish from sibling tools by specifying the context.

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

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

Description clearly says when to use the tool: 'before creating or reviewing posts.' It provides the context of needing connected targets for a workspace. However, it does not explicitly state when not to use it or provide alternatives, but the guidance is sufficient for appropriate use.

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 indicate a read-only, non-destructive, idempotent operation. The description adds context about the scope (workspaces available to the authenticated user) and the optional filter, which is valuable beyond the annotations.

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

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

The description is a single, well-constructed sentence that immediately conveys the tool's purpose and key feature. No excess 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?

Given the presence of an output schema (not shown) and rich annotations, the description provides sufficient context for an AI agent to understand when to invoke this tool. It covers purpose, scope, and optional filtering.

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 input schema already includes a description for the single optional parameter (organization_id). Description coverage is 100%, so the tool description adds no new meaning beyond reiterating the filter option. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: listing Postly workspaces available to the authenticated user. It mentions the optional filter by organization, which distinguishes it from sibling tools like list_posts or list_organizations.

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 explicitly states when to use the tool (when an AI agent needs workspaces), but it does not mention when not to use it or provide alternatives among siblings. The guidance is adequate but lacks exclusion criteria.

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 indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds the 'before creating or scheduling a post' usage context, but does not elaborate on return structure or pagination behavior. It is adequate given the annotation coverage.

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

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

The description is a single, front-loaded sentence that efficiently communicates the tool's purpose and usage context. Every part earns its place with no wasted words.

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

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

The description provides adequate context for a lookup tool with an output schema. It explains when to use the tool, but does not describe the return format or handling of edge cases. However, given the output schema exists, the description is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 80%, with most parameters described in the input schema (query, platform, workspace_id, organization_id). The overall description does not add additional semantic details beyond what is already in the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool resolves publishing targets based on natural language, platform, organization, or workspace queries. It uses a specific verb (resolve) and resource (publishing targets), and distinguishes from sibling tools like postly_list_social_accounts by focusing on resolution before posting.

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 explicitly says when to use: 'when a user asks for channels by natural language... before creating or scheduling a post.' It implies the tool is for pre-publish resolution but doesn't name alternative tools for cases where specific IDs are already known. Still, the context is clear.

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

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

Annotations already indicate destructiveHint=true. The description adds that media files are uploaded as part of the update action, and email_subject is required for email targets. This provides useful procedural detail beyond the annotations.

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

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

The description is three sentences, front-loads the main purpose, and gives specific usage hints for media and email. Every sentence adds value, no redundancy.

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

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

Given the high parameter count and complex nested objects, the description covers the essential update capabilities and adds key procedural detail. It does not explain scheduling or platform overrides in depth, but the output schema and high schema coverage compensate.

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

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

Schema coverage is 80%, so the baseline is 3. The description adds context for media_file parameters and email_subject, but most parameters are adequately documented in the schema descriptions. The description does not significantly improve parameter understanding beyond what the schema provides.

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

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

The description clearly states the verb 'update' and the resource 'existing Postly post', listing specific editable aspects (content, media, labels, targets, schedules). It distinguishes from create operations by implying the post already exists.

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 tells when to use the tool and provides specific guidance for media files and email targets. However, it does not explicitly exclude use cases or mention alternatives like postly_create_post, leaving some ambiguity.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the description does not need to repeat these. The description adds context about when the tool is used (separate from publishing), but does not disclose additional behavioral traits such as rate limits, permissions, or side effects beyond what annotations provide. It does not contradict annotations.

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

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

The description is concise at two sentences. The first sentence clearly states the tool's purpose and level, and the second provides key usage guidance. Every sentence adds value, and it is front-loaded with the most critical 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?

The tool has 6 parameters (none required), an output schema, and comprehensive annotations. The description explains its role relative to sibling tools and outlines when to use it. It does not cover error handling or return value details, but the output schema exists to describe returns. Given the tool's complexity, the description is sufficiently complete.

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

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

Parameter schema coverage is 100% with thorough descriptions for each parameter (url, data, file, type, alt_text, file_name). The tool description does not add further meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description states it's a 'Lower-level media import tool for agents that need to upload media separately from publishing.' It clearly identifies the verb (upload), resource (media into Postly storage), and distinguishes from sibling tools by contrasting with normal create/update flows. The mention of various media types (attached, selected, generated, etc.) further specifies its scope.

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 explicitly advises: 'For normal create/update flows, prefer passing ... media directly through postly_create_post or postly_update_post media_file fields so the user approves one publishing action.' This tells when to use this tool (separate upload) and when to avoid it (prefer integrated flows with other tools), providing clear context and alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond this, such as the validation action and instructions for handling failures. There is no contradiction with annotations.

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

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

The description is a single paragraph of three sentences, clearly front-loading the main purpose. It is concise and each sentence adds value, though it could be slightly more terse.

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

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

Given the tool's moderate complexity, full schema coverage, and presence of annotations and output schema, the description provides comprehensive context. It covers the validation workflow, post-validation actions, and integration with sibling tools, making it complete for agent use.

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 input schema has 100% description coverage, with each parameter already well-documented. The description does not add significant per-parameter meaning beyond the schema, so it meets the baseline of 3 but does not exceed it.

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

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

The description clearly states the tool's purpose: 'Use this before creating, updating, scheduling, or publishing a post to check text and media against the selected Postly workspace channels.' It identifies the specific verb (validate), resource (post), and scope (against workspace channels), and distinguishes it from sibling mutation tools like postly_create_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 description provides clear guidance on when to use the tool ('before creating, updating, scheduling, or publishing a post') and what to do with the result (auto-fill, ask questions, offer to publish to ready channels). It also instructs how to handle media for subsequent tools. However, it does not explicitly list when not to use it or name alternative tools for other situations.

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