Postly MCP

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

Annotations already provide destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds useful context by mentioning that the tool can 'queue' or 'schedule' posts and that it 'Returns the mutation result, platform readiness, blockers, and any required follow-up data,' indicating possible partial failures or follow-up needs. However, it does not discuss irreversibility, permission requirements, or potential side effects of scheduling, so it only modestly expands on 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 long, front-loaded with the core action in the first sentence. The second sentence summarizes input categories, and the third summarizes output data. There is no redundancy or filler, making it efficient and well-structured for a complex tool.

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 parameters, nested objects, scheduling, platform overrides), the description provides a commendable high-level overview including input categories and output data. It omits some specifics like the email_subject requirement for email targets, but those are covered in the schema. The presence of an output schema and high parameter coverage means the description need not over-explain. It is complete enough for orientation, though not exhaustive.

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%), so most parameters are already documented. The top-level description groups inputs into broad categories ('content, target selections, schedules, platform settings, and client-provided media references'), providing a helpful mental model without adding specific parameter semantics. This is adequate but not exceptional, as it does not compensate for the few undocumented parameters.

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: 'Creates, queues, or schedules a Postly post for social or email/newsletter targets.' It clearly distinguishes the tool from siblings like postly_update_post and postly_delete_post by emphasizing creation, queuing, and scheduling. It also lists the types of accepted inputs, further clarifying the tool's 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 provides no explicit guidance on when to use this tool versus alternatives such as postly_validate_post, postly_upload_media, or postly_update_post. It does not mention prerequisites, exclusions, or cases where another tool should be used instead. The only implied usage is that it is for creating, queuing, or scheduling posts, but no when-not-to-use information is provided.

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, so the description doesn't need to restate destructiveness. It adds 'specific existing' to clarify the post must exist, and 'returns the mutation status' to describe the outcome. This is consistent with annotations and adds a small amount of context beyond them, but lacks details on error handling 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?

The description is a single, front-loaded sentence that states the action and result without unnecessary elaboration. Every word adds value, making it highly concise and well-structured.

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

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

For a simple delete tool with one required parameter, destructive annotations, and an output schema, the description is largely complete. It tells the agent what the tool does and what it returns. It doesn't mention edge cases like non-existent posts, but given the low complexity and the presence of an output schema to describe results, this 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?

The input schema already provides full coverage for the single parameter post_id (100% schema description coverage). The description adds only that the post must be 'existing', which is context about the operation rather than the parameter itself. The schema and description together are sufficient, but no additional parameter semantics are provided.

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 'Deletes' and identifies the resource as 'a specific existing Postly post', clearly distinguishing it from sibling tools like postly_update_post or postly_create_post. It also mentions the return value ('mutation status'), making the tool's purpose unambiguous.

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

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

The usage context is implied: the tool is for deleting posts, given the name and description. However, there is no explicit guidance on when to prefer this over alternatives, nor any mention of prerequisites or situations to avoid. The distinction from update operations is implicit.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds context that it supports date ranges and returns metrics for various source types, but does not disclose additional behaviors like pagination, rate limits, or platform-specific nuances. This is consistent with annotations and adds some value, but not significantly beyond them.

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, front-loaded with 'Fetches analytics', and every word earns its place. It is efficient and easy to scan.

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

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

Given that annotations cover safety and an output schema exists to document return values, the description is adequately complete. It covers the core purpose, source types, and date range support. It does not mention optional parameters or platform variations, but these are handled in the schema, so no significant gaps remain.

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 provides examples of source types ('social account, page, profile, location, or channel') that loosely map to platform and channel_id, but these are already elaborated in the schema's parameter descriptions. The description does not add substantive meaning beyond what the schema already provides.

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

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

The description clearly states a specific verb ('Fetches') and resource ('analytics for a connected Postly source'), and it distinguishes from sibling tools like postly_get_post_analytics by specifying 'social account, page, profile, location, or channel' rather than a post. It also implies a contrast with postly_list_analytics_sources by returning metrics rather than listing sources.

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 context about the intended input (a connected Postly source) and mentions date range filtering, which helps an agent understand when to use it. However, it does not explicitly state exclusions or alternatives (e.g., 'for post-level analytics, use postly_get_post_analytics'), so it stops short of fully explicit guidance.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds substantive behavioral context by enumerating the categories of information returned (platform rules, limits, settings, defaults, capture requirements), which goes beyond the abstract 'Get Channel Schema' title and 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 two sentences, front-loaded with the action and resource, and every clause adds value. The first sentence states functionality, the second sentence provides usage guidance. There is no fluff or repetition.

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

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

The tool is simple (one parameter), has a rich output schema, and annotations cover safety. The description fully covers the return content categories and the appropriate use case. There is no missing information that would prevent an agent from using it correctly.

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

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

The single parameter 'platform' is fully documented in the input schema, including a list of allowed identifier values (x, linkedin, etc.). The description does not add any additional meaning or context about the parameter beyond what the schema already provides, so the schema carries the full burden. 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 begins with a specific verb ('Returns') and clearly identifies the resource (platform rules, character and media limits, required settings, safe defaults, capture requirements) as well as the target ('supported Postly publishing channel'). This distinguishes it from sibling tools like create/delete/update/validate, which perform different actions.

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

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

The description explicitly states when to use the tool: 'Use it before creating or scheduling content when the channel requirements are not already known.' It provides clear context but does not mention when not to use it or name alternative tools (e.g., postly_validate_post), so it stops short of a 5.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'sanitized' which indicates the returned details are filtered, providing additional behavioral context beyond the annotations. It does not contradict 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 clear sentence, front-loaded with the action and object, with no unnecessary 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 tool is simple with one parameter and an output schema, so the description need not explain return values. It adequately states the purpose and the key qualifier 'sanitized,' but it doesn't mention error conditions or permission requirements; however, these are less critical given the read-only annotations. Overall it is sufficient 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?

The input schema fully describes the single parameter post_id, and the description does not add syntax or format details beyond that. Since schema coverage is 100%, the baseline is 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 the specific verb 'Retrieves' and the resource 'sanitized details for a specific Postly post.' It distinguishes from sibling tools like postly_get_post_analytics and postly_get_post_status by focusing on post details rather than analytics or status.

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

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

The description provides no explicit guidance on when to use this tool instead of alternatives like get_post_analytics or get_post_status. The intent is implied through the word 'details,' but no alternatives or exclusions are mentioned.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral context: it specifies the post must be published and the platform must be supported. It does not discuss rate limits, auth, or error conditions, but given annotations, the bar is lower and this mild addition is acceptable.

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 concise sentences with no redundant information. It front-loads the core action and result, making it easy to scan. Every sentence earns its place.

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

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

For a read-only analytics tool with a full output schema and complete parameter documentation, the description is sufficiently complete. It identifies the post-level scope and supported platforms, which helps selection. It could add a note about needing prior setup via list_analytics_sources, but the schema parameter descriptions already cover that linkage, so the overall context is adequate.

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 additional parameter-level meaning beyond what the schema already provides; it only mentions 'analytics source' which loosely references channel_id and platform. Since the schema already documents parameters thoroughly, the description adds little extra value.

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

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

The description clearly states the tool fetches analytics for a published Postly post, using a specific verb ('Fetches') and resource ('analytics for a published Postly post'). It also mentions returning metrics, and the title 'Get Post Analytics' aligns with this. This distinguishes it from sibling tools like account analytics or 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?

The description implies usage for post-level analytics but does not explicitly contrast with alternatives like postly_get_account_analytics. It states 'for a published Postly post on a supported platform,' giving context, but lacks explicit when-to-use or when-not-to-use guidance. Sibling names help, but the description itself offers only implied usage.

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, establishing a safe read operation. The description adds context about the 'current' nature of the data and that it includes delivery counts, which are not captured in the annotations. However, it doesn't disclose potential error conditions or rate limits, and the output schema likely covers return values.

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

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

A single, clear sentence that states exactly what the tool does with no filler. It's appropriately short for a simple retrieval tool.

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, annotations, schema, and output schema cover the essentials for a simple read-only tool. Missing explicit usage guidance compared to alternatives, but the tool's purpose is clear and the risk of misuse is low given the read-only annotations.

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 provides 100% coverage for the single post_id parameter with the description 'Postly post ID.' The tool description adds no additional meaning beyond 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 uses a specific verb 'Retrieves' and identifies the resource ('publishing status and delivery counts' for a Postly post). It clearly distinguishes from sibling tools like get_post (content) and get_post_analytics (analytics).

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 implies the tool is for checking status and delivery counts but doesn't explicitly state when to use it over alternatives such as get_post or get_post_analytics. No exclusion or alternative guidance is provided.

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

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

Annotations already convey that this is a safe, read-only, idempotent operation. The description adds a useful behavioral detail about separating published counts from queued/processing posts, but it does not disclose pagination behavior, default time range, or timezone handling, so it only partially adds value 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, front-loaded sentence that immediately states the purpose and adds a key detail about output composition. It is concise, with no unnecessary words, and is 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 13 optional parameters, a more detailed description could clarify the various filtering dimensions. However, the rich input schema (with detailed property descriptions) and the presence of an output schema largely compensate, and the description captures the core purpose adequately for an agent to formulate a request.

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 85% parameter description coverage, with detailed descriptions for options like relative_range and timezone. The tool description itself adds no parameter-specific meaning, so it earns the baseline 3 for relying on the schema to document parameters.

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 ('Returns') and clearly identifies the resource ('publishing activity'), further specifying that it separates published delivery counts from queued/processing posts. This distinguishes it from sibling tools like postly_get_post_status or postly_list_posts, which focus on individual post states rather than aggregate activity counts.

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 implies usage for retrieving activity summaries over a date/time range, but it does not explicitly state when to prefer this tool over alternatives or mention exclusions. It lacks direct guidance on choosing between this and related tools such as postly_get_account_analytics or postly_list_scheduled_posts.

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, covering the safety profile. The description adds context about the scope (one workspace vs all) and grouping, but these are largely reflected in the schema and output schema. It does not disclose additional 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?

The description is concise: two sentences, front-loaded with 'Lists', and every sentence adds value without unnecessary 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?

The tool is simple with two optional parameters and has a full output schema and comprehensive annotations. The description, together with the schema and annotations, provides a complete understanding of the tool's purpose, scope, and safety.

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?

Both parameters are fully described in the input schema (100% coverage). The description aligns with the schema's parameter meanings but does not add extra semantic detail beyond what the schema already provides.

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

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

The description clearly states the tool lists connected accounts, pages, profiles, locations, and channels that support analytics, for one or all accessible workspaces. It distinguishes from siblings like list_social_accounts by explicitly focusing on analytics sources and mentions grouping by workspace.

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 context for usage: it lists analytics sources and supports workspace filtering or scanning all workspaces. However, it does not explicitly mention when not to use this tool or name alternative tools, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds useful context about the return value ('organization identifiers and metadata') and the scope ('authenticated connection'), but does not go into details like pagination or data volume. Since annotations cover the safety profile, this is adequate but not rich.

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

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

Two short sentences, front-loaded with the primary action ('Lists Postly organizations') and no filler. Every word contributes to understanding the tool's function and output.

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 parameterless list operation with an output schema and comprehensive annotations, the description fully covers what the tool does, what it returns, and why it is useful. There are no gaps in context.

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 and schema coverage is 100%, so the description need not explain any inputs. Baseline for 0 params is 4; the description adds value by stating what the list contains and its purpose, which is sufficient.

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 ('Lists') and resource ('Postly organizations available to the authenticated connection'), and adds the purpose 'for workspace selection'. This clearly distinguishes it from siblings like list_workspaces by the level of the resource (organizations vs. workspaces).

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 context 'available to the authenticated connection' and implies usage for workspace selection, but does not explicitly name alternatives or exclusions. However, the purpose is clear enough that an agent can infer when to use this over sibling tools.

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

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

Annotations already signal read-only and idempotent. Description adds that results are sanitized and scoped to the authenticated connection, providing useful behavioral context 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?

A single sentence that is front-loaded with the action, then states optional filters and return type. No unnecessary 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?

With an output schema present and strong annotations, the description covers purpose, filters, and the scope of results. It's complete for a list operation, and the mention of sanitized summaries adds useful context.

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 status and workspace_id with descriptions. Description reinforces these as filters but does not clarify skip/limit semantics; however, their names and defaults are self-explanatory. With 50% schema coverage, the description partially compensates but not fully.

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 lists recent Postly posts with optional filters, using a specific verb and resource. It distinguishes from siblings like postly_get_post and postly_list_scheduled_posts by emphasizing 'recent' and 'sanitized summaries'.

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 clear context: use for listing posts with optional workspace/status filters. However, it doesn't explicitly mention alternatives or when not to use it, such as for retrieving a single post or scheduled posts.

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 provide readOnlyHint, idempotentHint, and destructiveHint false, establishing a safe read operation. The description adds value by stating the return includes the resolved window, counts, and matching post summaries, clarifying what the agent will receive. This goes beyond the annotations, though it doesn't discuss pagination or ordering.

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 states the action, lists the key filtering options, and summarizes the output. There is no redundant or filler content, and 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 has 9 optional parameters and an output schema, the description covers the core behavior and return concept adequately. It doesn't explain filter exclusivity or default behavior, but these are inferable from the schema and the output schema handles return details. A compact but sufficient description for a read-only listing 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 coverage is 78%, with detailed descriptions for most parameters (date, timezone, relative_range, scheduled_from, scheduled_until, workspace_id, organization_id). The description offers a concise high-level synthesis of the filter modes but doesn't add extra meaning for skip/limit or parameter interactions. Since the schema carries the bulk of parameter semantics, a 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 lists scheduled posts and specifies multiple filtering dimensions: workspace, date, relative date window, or explicit time range. It distinguishes itself from sibling tools like postly_list_posts by targeting scheduled posts and from postly_get_post_status by indicating it returns summaries and counts.

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 makes it apparent when to use this tool: whenever you need to list scheduled posts with flexible time windows. It doesn't explicitly mention alternatives like postly_list_posts or provide exclusions, but the scope is clear enough to guide selection. Missing explicit when-not-to-use guidance prevents a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the safety profile is covered. The description adds that only 'connected' targets are listed and that output includes 'identifiers and metadata,' but it does not disclose potential caveats such as pagination, ordering, or authorization 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 two sentences, front-loads the primary purpose, and contains no redundant or filler content. Every phrase adds value.

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 simple one-parameter schema and the presence of an output schema, the description adequately covers the tool's behavior. It states what is listed and what is returned, so no critical information is missing for this straightforward list operation.

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

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

The schema provides 100% coverage for the single parameter workspace_id with a description. The tool description does not add further meaning or context about the parameter beyond what the schema already gives, so the baseline 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 it 'Lists connected social channels and email/newsletter targets for a Postly workspace' and specifies the return type. This distinguishes it from sibling tools like postly_list_posts and postly_list_workspaces by identifying the exact resource (publishing targets).

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 no guidance on when to use this tool versus alternatives, nor does it mention any exclusion scenarios or prerequisites. It simply states what the tool does, so usage context is absent.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful context about the authenticated connection and states that it returns workspace identifiers and metadata, which clarifies the scope. It does not mention pagination or rate limits, but for a simple list tool this is acceptable.

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 only two sentences, front-loads the action, and contains no redundant information. Every clause adds value: the authenticated connection, the optional filter, and the return type.

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 (one optional parameter, full schema coverage, and an output schema), the description adequately covers purpose, scope, and filtering. It does not need to explain return values because the output schema exists. There are no obvious gaps for an agent to correctly invoke this 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 input schema already fully describes the only parameter (organization_id) with a clear description, and schema coverage is 100%. The tool description merely echoes 'optionally filtered by organization' without adding new details about format, behavior, or relationships. Therefore, the baseline 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 action ('Lists Postly workspaces') and the resource ('workspaces available to the authenticated connection'). It also mentions the optional organization filter, which adds specificity and distinguishes it from sibling tools like list_organizations and list_social_accounts.

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 context about the authenticated connection and optional filtering, but it does not explicitly state when to use this tool over alternatives such as postly_list_organizations or postly_list_social_accounts. No exclusions or alternative tool names are mentioned, leaving the agent to infer the appropriate usage.

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 provide strong safety signals: readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds minimal context about behavior beyond that, such as 'Returns matching channels and workspace context' and the pre-creation use case. It does not add details like pagination or result limits, but with annotation coverage and an output schema, the description is adequate though not particularly rich.

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

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

The description is two concise sentences, front-loaded with the primary action and purpose. No redundant words, and it earns its place with specific detail on resolution dimensions and output. Excellent structure and length for the complexity of the tool.

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 5 optional parameters, no required args, comprehensive annotations, and an output schema (not shown but present). The description provides a high-level summary of the output ('matching channels and workspace context') and the usage context. It does not explain default behavior with no filters (e.g., does it return all targets?), but given the output schema and annotations, the description is sufficiently complete for an agent to select and invoke the 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 high (80%) since 4 of 5 parameters have descriptions. The description reinforces the parameter purposes by mentioning 'by platform, organization, workspace, or name', aligning with the query, platform, workspace_id, and organization_id fields. The 'limit' parameter lacks a description in the schema and the description does not compensate, but the name is self-explanatory. Overall, the description adds modest value beyond the schema.

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

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

The description clearly states the tool 'Resolves publishing targets by platform, organization, workspace, or name' with a specific verb and resource. It also positions the tool relative to the post lifecycle ('before a post is created or scheduled') and distinguishes it from sibling tools like create_post or list_social_accounts by focusing on resolution of targets rather than creation or general listing.

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 this tool: 'before a post is created or scheduled' and what it does (resolves targets). It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to understand this is the pre-publication target resolver, distinct from general list or creation tools.

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 and readOnlyHint=false, so the mutation risk is clear. The description adds useful behavioral context: it accepts client-provided media references for import in the same action and returns mutation results, platform readiness, blockers, and follow-up data. This goes beyond the annotations by explaining the import behavior and the nature of the response.

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 and front-loaded, with two sentences that efficiently state the purpose and key additional behaviors. No redundant information is included, and it is easy to scan.

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

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

The tool is complex with 25 parameters, nested objects, and an output schema. The description gives a solid high-level overview but does not mention important complexities such as optionality of most fields, the need for post_id, or the existence of auxiliary tools like postly_get_channel_schema for platform-specific guidance. Given the complexity, the description is adequate but incomplete for full self-sufficiency, hence a 3.

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%, so the schema already documents most parameters. The description adds high-level meaning by grouping parameters into categories (content, media, labels, targets, schedules) and highlights the media import feature, but it does not explain individual parameters beyond what the schema provides. This is a baseline 3 for high schema coverage.

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 function: 'Updates editable content, media, labels, social or email/newsletter targets, and schedules for an existing Postly post.' This is a specific verb+resource and distinguishes it from siblings like create, delete, get. It also mentions unique capabilities like accepting client-provided media references for import.

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 implies usage for modifying an existing post ('for an existing Postly post'), but it does not explicitly state when to use this tool versus alternatives (e.g., create for new posts, delete for removal). No exclusions or alternative recommendations are provided, so it relies on the sibling tool names for context.

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. The description adds that the tool returns a 'durable Postly media object and upload usage details,' which is useful context. However, it does not disclose potential side effects like storage costs, rate limits, or whether the media is immediately accessible. It doesn't contradict annotations, but adds only modest behavioral context beyond them.

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 states the purpose, lists supported input formats, and describes the return value. Every phrase earns its place; there is no redundant or vague wording. This is a model of concise, informative tool documentation.

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, one nested object, and an output schema. The description covers the core behavior (import media, return durable object and usage details) and input modes. It doesn't explain return format details, but the output schema exists to provide that. Given the complexity and existing structured metadata, the description is complete enough for an agent to use it correctly.

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

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

The schema has 100% description coverage for all parameters, so the baseline is 3. The description adds a compact summary of input types ('client-provided file reference, URL, data URL, or base64 payload') and mentions that file_name is required for base64/data, but these details are already in the schema. The description adds no further meaning beyond what the schema already provides.

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

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

The description clearly identifies the tool's function: 'Imports media into Postly storage independently of a post mutation.' It specifies the resource (Postly media storage) and the action (upload/import), and lists accepted input forms (file reference, URL, data URL, base64). This distinguishes it from sibling tools like postly_create_post or postly_update_post, which focus on post mutations.

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 phrase 'independently of a post mutation' establishes a clear usage context: this tool is for uploading media that may later be attached to a post. It implies it should be used when you need a durable media object before creating or updating a post. While it doesn't explicitly name alternatives (e.g., embedding media directly in a post mutation), the context is sufficient for an agent to understand when to invoke it.

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 agent knows it is a safe read operation. The description adds behavioral detail by specifying what is returned: validation status, errors, warnings, platform readiness, and applicable limits. This goes beyond the annotations without contradicting them.

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 core action, no redundant phrasing. The first sentence states what it checks; the second states what it returns. Every word contributes value.

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 a large schema and an output schema, which already carry detailed parameter and return information. The description captures the essential purpose and output scope. It doesn't mention prerequisites like workspace_id or the recommendation to call postly_get_channel_schema, but those are in the schema, so the description is adequate in context.

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 schema already documents every parameter. The description groups params into categories (text, media, platform settings, schedules, targets) which helps orient the agent, but it adds no new syntax or format details. Baseline 3 is appropriate given the high schema coverage.

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 ('Checks') and clearly identifies the resource ('proposed post text, media, platform settings, schedules, and targets') and the validation target ('against Postly and platform-specific requirements'). It distinguishes from sibling tools like create_post or get_post_status by focusing on pre-publication validation and lists return types (validation status, errors, warnings, platform readiness, limits).

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 word 'proposed' implies the tool is for validating a draft before publishing, giving clear contextual use. However, it does not explicitly name alternatives (e.g., 'use before create_post') or state when not to use it, so it stops short of the highest score.

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