AdaptlyPost

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

Goes well beyond the annotations: it discloses independent per-item processing ('one bad item fails alone while the rest are scheduled'), exact return shape, input-order results, the requirement to 'read every row,' and the surprising behavior that a past scheduledAt publishes immediately rather than being rejected. 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?

Seven dense sentences cover capacity, shared vs per-item parameters, failure semantics, return format, past-time behavior, prerequisites, and routing to create_post. No filler or repetition; core constraints are front-loaded.

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

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

For a tool with 17 parameters, an output schema, and complex cross-platform behavior, the description is complete: it covers capacity, partial failures, return semantics, immediate publish edge case, platform prerequisites, and when to use an alternative. Nothing needed to call it correctly is left out.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between top-level shared parameters (platforms, connection-id arrays, timezone, configs) and per-item fields, plus which configs are required when a platform is selected. This exceeds simple schema restatement.

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

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

The description opens with a specific verb and resource: 'Schedule up to 100 posts in one call to the same platforms and accounts.' It clearly differentiates from the sibling create_post by stating when bulk scheduling is appropriate and that this tool has no draft mode.

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 directs users to 'Call list_accounts first,' names platform-specific prerequisites (TikTok and Pinterest configs), and states 'Use create_post for a single post or a draft; this tool has no draft mode.' This gives the agent clear routing logic versus the nearest alternative.

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

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

Goes well beyond the annotations by disclosing that publishing is asynchronous per platform, the response is not the final outcome, and list_post_results must be read for per-platform success or failure. It also clarifies scheduledAt semantics, draft behavior deferring validation to publish_draft, and the mediaUrls failure condition, none of which are visible from annotations alone.

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

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

Dense but well-organized: each sentence carries a distinct requirement or behavioral caveat, and the most important semantics are front-loaded. The description covers a very complex 25-parameter tool without redundancy or 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?

Given the tool's complexity, the description covers all major failure modes and prerequisites: account ID sourcing, per-platform config requirements, async response handling, media URL provenance, and sibling routing. The output schema already exists, so the description correctly focuses on behavior not apparent from structured fields.

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?

Though schema coverage is 100%, the description adds critical semantic meaning beyond the schema: omitting scheduledAt publishes immediately, future scheduledAt sets status SCHEDULED, saveAsDraft defers validation, mediaUrls must originate from upload_media or the call fails, and each platform needs exactly one account. These relationships are not inferable from the property descriptions alone.

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

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

States a specific verb, resource, and scope: 'Create one post for one or more platforms' with immediate publish, schedule, or draft modes. Earlier in the description it distinguishes itself from update_post, publish_draft, and bulk_schedule_posts, so an agent can select it correctly without opening sibling schemas.

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

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

Provides explicit guidance: call list_accounts first to get connection IDs, use bulk_schedule_posts for many posts on the same accounts, and use update_post or publish_draft for existing posts. It also gives platform-specific requirements like TikTok privacyLevel and Pinterest boardId, making the correct usage unambiguous.

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

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

Beyond the destructiveHint annotation, the description reveals that deletion only removes the record, not the actual platform content for already-published posts. It also discloses irreversibility, workspace access restriction, and the exact error message for unauthorized or missing posts.

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

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

The description is concise yet comprehensive, organized logically from action to usage guidance to caveats to error handling. It packs necessary details without redundancy, making it easy to scan and understand.

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 one-parameter destructive operation, the description covers all relevant context: what it does, when to use it, side effects on different post statuses, workspace restrictions, expected return value, and irreversibility. No important information is missing.

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

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

The only parameter (id) is fully described in the input schema ('Post ID to delete, from list_posts or create_post'), so coverage is 100%. The tool description does not add additional parameter semantics beyond what the schema already provides, keeping the score at the baseline for full 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 states a clear, specific action ('Delete a post record from AdaptlyPost by id') and distinguishes it from siblings by noting when to use update_post instead. It also clarifies the tool's scope (only DRAFT or SCHEDULED posts cancel publishing).

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

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

Explicitly tells when to use this tool ('Use it to cancel a DRAFT or SCHEDULED post before it goes out') and when to prefer an alternative ('Prefer update_post to change a post instead of deleting and recreating it'). Also explains behavior for COMPLETED or PARTIAL_FAILURE posts, giving complete usage 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?

The description goes beyond the readOnly annotation by explaining data freshness (last 180 days, refresh every few hours), behavior for unsupported platforms, and the LinkedIn platform restriction. It also notes that metrics no platform reports are null, providing clear behavioral expectations.

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 detailed but every sentence carries useful information. It front-loads the core purpose, then covers output shape, usage guidance, platform behavior, freshness, and sibling tools without unnecessary wording.

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 is present and the input schema is fully described, the description provides complete context: what metrics are returned, how the comparison window works, platform restrictions, data freshness, and when to use alternative tools. No important caller-relevant behavior is missing.

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

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

Schema descriptions already cover from, to, and platforms, but the tool description adds key semantics: metrics are based on posts published between from and to, the comparison window is the same length immediately before from, and omitting platforms means all platforms with analytics. This adds meaningful context 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 returns workspace-wide performance metrics for a date window, including specific metrics and comparison values. It distinguishes itself from related analytics tools by naming get_analytics_timeseries, get_platform_breakdown, and list_post_analytics as 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?

It explicitly says to use this for 'how did we do this month' questions and follower counts. It also provides guidance on when to call trigger_analytics_sync first and names alternative tools for trends, platform breakdowns, and individual post analytics.

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 readOnlyHint annotation already establishes that this is a safe read operation, and the description adds meaningful context about sync states, the meaning of historyHorizonAt, and the reconnect behavior. It could have explicitly stated it makes no changes, but the annotation covers that.

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

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

The description is slightly verbose and repeats some field names, but it packs essential usage guidance, status meanings, and a caveat about reconnects into a compact monologue. It is not bloated or redundant enough to hurt clarity.

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

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

The description fully explains the return semantics, the statuses, the meaning of the history horizon, and the reconnect flow, along with actionable advice for the agent. It leaves no critical operational detail unexplained.

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

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

There are no parameters, and the description explicitly states 'Takes no arguments.' The schema coverage is complete, so there is no ambiguity.

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 reports analytics sync freshness per connected account, which distinguishes it from analytics overview, timeseries, and platform breakdown siblings. It explicitly enumerates the returned status fields and their meaning.

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

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

The description gives explicit guidance on when to call this tool: when numbers look stale or empty, and after trigger_analytics_sync to observe the run finish. It also tells the agent not to keep querying if needsAnalyticsReconnect is true.

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

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

Annotations already cover read-only and non-destructive nature, so the description correctly avoids redundancy. It adds valuable behavioral details beyond annotations: the aggregation semantics (followers as latest count, other metrics as sums over published posts, null for unsupported platforms) and the output shape with one point per bucket. This is meaningful context that helps an agent interpret results correctly.

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-structured paragraph that front-loads the core purpose (metrics and granularity), then explains the return format and aggregation rules, and concludes with sibling routing. Every sentence contributes essential information with no fluff or repetition. It is detailed yet efficiently organized.

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 an output schema and full parameter documentation, the description covers all critical operational details: what metrics are returned, how they are aggregated, the null behavior, and how it fits with sibling tools. An agent has everything needed to invoke it correctly and interpret the response.

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 each parameter having a descriptive explanation. The description itself does not add significant parameter-level meaning beyond the schema; it only references granularity implicitly via 'bucketed by day (default), week or month' which is already in the schema. The baseline of 3 is appropriate given 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 returns time-bucketed metrics (views, likes, comments, shares, followers, posts published, engagement rate) for trend analysis, with explicit granularity options. It distinguishes itself from siblings by naming get_analytics_overview for totals and list_post_analytics for post-level spikes, making its unique 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?

It explicitly states the intended use case ('for trend questions such as...') and provides clear guidance on when to use alternatives ('Use get_analytics_overview for totals and list_post_analytics to see which posts drove a spike'). This gives an agent precise decision criteria for tool selection.

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 readOnlyHint annotation already signals no side effects. The description adds meaningful behavioral detail by explaining that the response includes 'supportedMetrics' and the caveat about comparing only metrics both platforms report. This goes beyond the annotation to clarify data-availability behavior.

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

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

The description is front-loaded with purpose and differentiation, and the technical note about supportedMetrics is necessary for correct usage. It is slightly dense but not verbose, with no redundant 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?

With an output schema present and the description outlining the return structure (per-platform rows, metric fields with previous/delta, supportedMetrics), the tool is fully specified for an agent to call and interpret results. No missing behavioral or data-format information.

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 JSON schema fully describes both parameters (from/to, ISO 8601, comparison window) with 100% coverage. The description adds no extra parameter semantics beyond repeating that there is no platform filter, so it stays at the baseline 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?

States a specific purpose: 'The overview metrics split per platform for a date window' and explicitly contrasts with the sibling 'Use get_analytics_overview for the combined total.' The use case 'for which platform performs best comparisons' makes the tool's role 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?

Provides explicit guidance to use get_analytics_overview for combined totals, the primary alternative. It also instructs to 'compare only metrics both platforms list there,' clarifying how to handle platform-specific metric availability, which is actionable usage advice.

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, openWorldHint=false. The description adds valuable context about workspace scope ('visible only within the token's workspace') and error behavior ('any other id returns "Post not found or access denied"'), enhancing transparency 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?

The description is concise but informative, using three sentences to convey the tool's purpose, returned content, and usage guidance. It avoids redundancy while providing necessary distinctions from sibling tools.

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 covers the tool's primary function, output contents, error/access behavior, and relationship to other tools. Given the simple parameter and the provision of an output schema (not shown but indicated), it provides sufficient context for an agent to use 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?

The single parameter 'id' is fully described in the schema (coverage 100%) and the description reinforces its origin ('Post ID from create_post, bulk_schedule_posts, or list_posts'). This adds practical context beyond the schema's basic type definition.

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 retrieves a single post's full record by ID and enumerates the included fields (text, contentType, status, scheduledAt, timezone, platforms with connection/status/errorMessage/media). It distinguishes itself from related tools like list_posts and list_post_results.

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 instructs when to use this tool ('inspect content before update_post or publish_draft') and when to use alternatives (list_post_results for per-platform outcomes, list_posts for finding IDs). This provides clear selection 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 only declare readOnlyHint=false / destructiveHint=false / openWorldHint=false, which is minimal. The description goes well beyond that: it explains the tool only mints a URL, that the caller must perform the PUT and verify a 2xx response, and that skipping this causes create_post/bulk to reject with 'Media file(s) not found in storage'.

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

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

Front-loaded with the core action and return contract, then the workflow requirement, then the sibling preference, then parameter guidance. Every sentence carries actionable information with no filler.

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

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

Despite an output schema existing, the description still clarifies what uploadUrl and publicUrl are for and how they feed into create_post mediaUrls. Combined with the workflow and supported-type constraints, an agent has everything needed to invoke and complete the upload correctly.

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

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

Schema description coverage is 100% and the mimeType enum is already defined in the schema, so the schema does the heavy lifting. The description repeats the per-file fields (fileName, mimeType) and lists supported types, adding only marginal value over the structured data, so baseline 3 applies.

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

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

States a specific verb and resource (mints presigned upload URLs for direct file uploads) and explicitly differentiates itself from the sibling upload_media by describing the size/ownership conditions that select it. An agent can pick between get_upload_urls and upload_media without opening either schema.

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

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

Names the alternative (upload_media) and the exact condition to prefer it ('public URLs and for inline files under 30 MB'), and states when to use this tool instead ('larger files you hold yourself'). It also documents the mandatory follow-up workflow (PUT to uploadUrl, confirm 2xx before using publicUrl) and the failure mode if skipped.

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

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

The description clearly states it takes no arguments and returns a read-only list of accounts, aligning with the readOnlyHint annotation. It doesn't mention potential throttling or data pagination, but no destructive or side-effect behavior is hidden; annotation and description are consistent.

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

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

The description is compact and well-structured: it states the result, the key usage imperative, the alternative for other use cases, and the no-arguments fact. Every sentence adds necessary guidance without 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 empty schema and no parameters, the description covers everything an agent needs: what it returns, when to call it, how to use the IDs, and which sibling tools handle related but different tasks. The output schema likely provides the return structure, so no further detail is needed here.

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

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

The tool has zero parameters and the schema already reflects that with an empty properties object. The description reinforces 'Takes no arguments,' so there is no missing parameter guidance; a small deduction because no mention of output schema details, but that's not parameter 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?

Clearly states the tool lists social accounts connected to the workspace across all nine platforms, and enumerates the returned fields. It also contrasts with related tools for posting and analytics, making its 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?

Explicitly instructs to call this before create_post, update_post, or bulk_schedule_posts to obtain IDs, and tells which ID arrays to use for each platform. It also directs users to list_posts or list_post_results for post history/publishing status, leaving no ambiguity about when 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?

The annotations (readOnlyHint: true, destructiveHint: false) are consistent with a read-only analytics tool. The description discloses behavioral details such as null postId for discovered posts, metric nulls for unsupported platforms, and sort behavior (newest first for PUBLISHED_AT), fully informing the agent of side effects and limitations.

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

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

The description is dense but efficient, using semicolons to separate related ideas. It packs essential information (scope, sorting, pagination, platform caveats) without redundancy or filler, making it 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?

It fully describes the return shape (posts array, total, page, limit, hasMore) and per-post fields, including metrics and platform-specific null behavior. Edge cases like unsupported platforms and pending LinkedIn analytics are covered, so an agent knows exactly what to expect.

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?

All six parameters have explicit descriptions in the schema, covering meaning, defaults, and constraints. The overall description adds context, such as the comparison window for 'from' and platform restriction semantics, enriching the schema with operational details.

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

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

The description states a specific action ('Per-post metrics for posts published inside the window'), highlights typical use cases ('top posts', 'which post got the most comments'), and clearly distinguishes it from list_post_results by stating 'Not for publishing status'. This makes the tool's purpose unmistakable.

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

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

It explicitly names the alternative for publishing status ('use list_post_results for that') and explains when to use this tool (for per-post analytics). It also provides practical filtering guidance (platforms with no analytics are ignored, LinkedIn pending approval), leaving no ambiguity about 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 mark it read-only; description adds the critical behavior that each platform reports separately and that publishing is asynchronous, so responses only confirm queueing and you must poll until no PENDING/PUBLISHING. This goes 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?

Four sentences, each earning its place: purpose, return shape, usage guidance, and alternative. Well structured but could be slightly more concise with bullets; still 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?

Given an output schema exists, description covers the return shape and the polling logic, plus how to use FAILED rows for retry_failed_platforms. Complete for an agent to call 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 covers 100% of the single parameter (id) with sources (create_post, publish_draft, etc.). Description doesn't add extra semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Get) and resource (one post's per-platform publishing outcomes), and distinguishes from get_post (which gets content and schedule) and list_posts. It clearly defines what it returns: { postId, status, results[] }.

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 call it (after create_post, publish_draft, or retry_failed_platforms), explains the asynchronous nature and polling requirement, and names get_post as the alternative when content and schedule are also needed.

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

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

Annotations already indicate readOnlyHint and non-destructive behavior. The description adds useful context about return shape and pagination semantics but does not contradict annotations or introduce unexpected 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 paragraph with two sentences, but it repeats some schema details (e.g., date bounds, pagination). It is not overly verbose but could be slightly more concise by omitting redundant parameter explanations.

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 fully specifies what is returned (posts array with status and platforms, total, hasMore) and how to paginate. It also mentions appropriate use cases and sibling tools, making it complete for an agent to decide when and how to call it.

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

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

Schema descriptions cover 100% of parameters with clear explanations of filters and pagination. The description reinforces date and status semantics but does not add significant new meaning beyond the schema; still, it helps clarify usage.

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

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

The description clearly states the tool lists posts in the workspace with filtering and pagination, and explicitly distinguishes it from get_post and list_post_results. The verb 'list' and resource 'posts' are specific.

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 provides explicit guidance: 'Use this to find post ids or check what is already queued.' It also mentions alternatives for single-post details and per-platform outcomes, and explains filtering/pagination 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?

Clearly discloses side effects: moves to PENDING, queues per-platform publishing, content reaches networks and cannot be recalled, and explains failure conditions (disconnected account, missing TikTok privacyLevel). This matches the readOnlyHint=false annotation and adds important behavioral context beyond the schema.

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

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

The description is dense but every sentence carries necessary information: accepted statuses, scheduling behavior, failure modes, and cross-references to sibling tools. No redundant filler or vague phrasing.

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

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

Given the output schema exists and the tool has moderate complexity, the description fully covers preconditions, post-conditions, failure modes, and follow-up actions. It leaves no critical ambiguity about what the tool does or when to use it.

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

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

The schema already covers all three parameters with descriptions, and the tool description adds crucial semantics: timezone does not shift scheduledAt, and omitting scheduledAt or passing a past time publishes immediately. This goes beyond simple field listings.

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

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

States a specific verb and resource ('Publish a DRAFT post'), clarifies that SCHEDULED posts are also accepted, and explicitly distinguishes from create_post for new content. This makes the tool's purpose unmistakable and differentiates it from siblings.

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

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

Gives explicit when-to-use guidance: publish now or schedule, accepts DRAFT/SCHEDULED, fails on other statuses, and directs users to update_post for fixes and create_post for new content. Also recommends checking list_post_results afterwards, which is actionable.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description reveals key behaviors: only FAILED rows are reset, other ids are ignored, failure condition if none match, post moves to PUBLISHING, retry is asynchronous, and content cannot change. These are critical behavioral details that annotations do not capture.

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

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

The description is compact yet information-dense. It front-loads the core action, then adds conditions, async behavior, prerequisites, and retry criteria in a logical flow. No redundant sentences; every clause earns its place.

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

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

Given the tool's complexity, the description covers all essential aspects: operation, conditions, error case, async behavior, dependency on list_post_results, retry criteria, and immutability of content. The output schema exists, so return value details are not required. The description is fully sufficient 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 already fully documents both parameters (id and platformIds) with clear descriptions, including the requirement that platformIds come from FAILED rows of list_post_results. The description reinforces this and adds context about the retry logic and source, but does not introduce new parameter meanings beyond what the schema provides. Since schema coverage is 100%, the baseline is 3; the description adds a small extra value by tying the parameters to the retry workflow.

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

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

The description states a specific action on a specific resource: 'Re-queue publishing for a post's FAILED platforms.' It clearly distinguishes the tool's scope (only FAILED platforms) and mentions the sibling list_post_results for gathering prerequisites, making its 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 description provides explicit when-to-use guidance: get platformIds and errorMessage from list_post_results first, retry only after fixing the cause (reconnected account, replaced media), and explicitly warns not to retry platform-side restrictions that will just fail again. It also notes the async nature and where to check outcome, giving clear context 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?

The description discloses all relevant side effects: it queues accounts, runs in the background, returns a queued status with cooldown info, and explicitly states it changes no content. It also details the cooldown semantics and that repeated calls within the cooldown do not queue again, making the tool's behavior fully transparent. 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 front-loaded with the primary purpose, then provides important usage and behavior details in a logical order. Though it is a single paragraph, every sentence contributes critical information without fluff or redundancy. Length is appropriate for the 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?

For a tool with no input parameters and a likely simple output, the description gives sufficient context: it mentions the output fields (queued and cooldownSecondsRemaining), explains the background execution, and guides follow-up via get_analytics_sync_status. An agent can confidently invoke this tool based solely on this description.

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

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

There are zero parameters, so the description need not explain any. It explicitly states 'Takes no arguments,' which is clear and sufficient. Baseline for 0 params is 4, and the description adds no unnecessary detail, so it remains at that score.

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: to refresh analytics immediately rather than waiting for the scheduled sync. It explicitly describes what happens (every connected account is queued, last 7 days re-read) and contrasts it with the scheduled sync and get_analytics_overview, making its distinctive function obvious.

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 specific, actionable guidance: use it after publishing or when get_analytics_overview shows a stale lastSyncedAt. It also explains the cooldown behavior and instructs not to retry in a loop, and tells the agent to poll get_analytics_sync_status for completion. This is exemplary usage direction.

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 only say readOnlyHint=false, openWorldHint=true, destructiveHint=false, so the description carries the burden of behavioral disclosure. It does this thoroughly: partial-update semantics, the platforms-rebuilds-targets exception, mediaUrls only taking effect with platforms, storage verification for SCHEDULED posts, and the exact error message for invalid states. This goes well beyond what annotations provide.

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

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

The description is dense but every sentence earns its place: state constraints, partial-update semantics, the platforms exception, the mediaUrls dependency, and sibling routing. It is front-loaded with the most important constraint (DRAFT or SCHEDULED only). It loses one point because the density makes it a long paragraph that an agent must parse carefully, and some details (e.g., 'use publicUrl values from upload_media') could arguably live in the schema.

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

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

For a 25-parameter mutation tool with no output schema, the description covers the critical behavioral traps: status restrictions, partial updates, the platforms rebuild semantics, mediaUrls dependency, and storage verification. The output schema exists, so return values need no explanation. Sibling routing is explicit. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value on top: it explains the partial-update semantics (omitted fields keep values), the critical exception that platforms rebuilds the target set, and the dependency that mediaUrls only works with platforms. It doesn't enumerate every parameter, but the schema already does that; the description clarifies the cross-parameter behavior that the schema cannot express.

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

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

The description opens with a specific verb and resource ('Update a DRAFT or SCHEDULED post in place') and immediately distinguishes itself from siblings by naming publish_draft, delete_post, and create_post. It also states the failure mode for published posts, so an agent can tell exactly what this tool does and does not do.

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 this tool (updating draft/scheduled posts) and when not to (published posts fail), and it names the alternatives: publish_draft to change status, delete_post to cancel, create_post for new posts. It also gives conditional guidance for platforms and mediaUrls, which is exactly the kind of routing an agent needs.

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

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

Annotations only declare write/open-world, but the description goes far beyond that: stored files are public immediately regardless of posting, server refuses private/internal/non-https sources, Content-Length is required, Content-Length and size limits are stated, formats are content-checked, and the return shape is named. This is rich behavioral context an agent cannot get from the annotations alone.

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

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

The description is dense but front-loaded: it leads with the purpose and mediaUrls use, then sources, limits, and the overflow alternative. Every sentence carries operational information; no filler.

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

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

For a mutation tool with open-world annotations and an output schema, the description still supplies all the constraints an agent needs: source options, error condition, format/size limits, public-exposure warning, overflow path to get_upload_urls, and how to use the returned mediaUrls. It is complete for correct invocation and safe 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics the schema does not: the two sources are combinable, the 30 MB decoded total is per call, the server streams URL sources and enforces Content-Length, and non-https/private URLs are refused. It does not, however, document the nested data/fileName/mimeType fields beyond what the schema already says.

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 (Upload) for a specific resource (images or videos to AdaptlyPost storage) and names the exact field (mediaUrls) it feeds. It also explicitly differentiates itself from the sibling get_upload_urls by naming the threshold (over 30 MB) that routes the agent there.

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

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

It gives explicit when/when-not guidance: use for conversation-attached media (files) or public URLs, use get_upload_urls for inline files over 30 MB, and error when both are omitted. This leaves little inference for selecting the right tool or argument shape.

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