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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description usefully adds the cross-tool ordering constraint that media must be uploaded first and the returned objects passed as `images`, plus the note that drafts still require a date under the current API contract. It does not mention failure modes, partial-channel failures, or what a successful call yields.

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

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

Three sentences, zero filler, and the payload description is front-loaded ahead of the prerequisite workflow. Every sentence carries either scope, enum semantics, or a dependency the agent must satisfy.

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 six-parameter create tool with no output schema, the description covers the prerequisites, the publish-mode fork, and the media flow, which is most of what an agent needs. The remaining gap is that it never says what the call returns (post ids, status) even though there is no output schema to carry that 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?

Schema coverage is 100%, so the baseline is 3, but the description adds provenance meaning the schema cannot express: channel ids originate from postsider_list_channels, dates/slots from postsider_find_slot, and image objects from postsider_upload_media_from_url. That is genuine value beyond the field-level descriptions.

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 first sentence names a specific verb and resource ('Create a post across one or more channels') and the second disambiguates the `type` enum values, which is the main behavioral fork of the tool. This clearly separates it from siblings like postsider_update_post_status and postsider_delete_post, which operate on posts that already exist.

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 routes the agent through the correct prerequisites by name: get channel ids from postsider_list_channels, get a slot from postsider_find_slot, and upload media via postsider_upload_media_from_url before passing the returned objects. What is missing is an explicit exclusion (e.g. use postsider_update_post_status or postsider_get_post instead when editing an existing post), so the agent must infer the create-vs-edit boundary.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so safety classification is covered. The description goes beyond them by disclosing blast radius (one id wipes every channel version in the group) and recommending user confirmation, which annotations cannot express. It does not add anything on reversibility beyond 'permanently', which the destructive hint already implies.

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

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

Three tight sentences, zero filler. The destructive scope is front-loaded, followed by the id semantics and then the safety prerequisite, which is the correct ordering for an irreversible operation.

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

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

For a one-parameter destructive tool with no output schema, the definition covers what an agent needs: destructive scope, id resolution rule, and a pre-call verification step. Annotations carry the remaining safety and idempotency signals.

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

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

Schema coverage is 100% with a single well-described parameter, so the baseline is 3. The description adds real meaning the schema lacks: any post id in a group is acceptable and resolves to deletion of the whole group, which changes how an agent chooses which id to pass.

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

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

States a specific verb and resource ('Permanently delete a post') and immediately clarifies the scope: a single id deletes an entire multi-channel group. This is materially more precise than the title and lets an agent distinguish it from siblings like postsider_pause_publishing or postsider_update_post_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?

It gives a clear prerequisite workflow - read the post first via postsider_get_post and confirm the channel versions with the user before calling. It names a sibling tool explicitly. It stops short of stating when NOT to use this (e.g., when pausing or status updates would suffice), which the sibling set suggests is relevant.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds useful context beyond that (value is UTC and derived from the configured posting queue), but does not disclose edge behavior such as what is returned when no slot is available or the queue is unconfigured.

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

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

Two sentences, no filler, and the core purpose is front-loaded ahead of the consumption directive. Every sentence earns its place by either defining the return value or telling the agent how to use it.

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

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

For a one-parameter, read-only tool with no output schema, the description covers both what is returned (the next free scheduling date-time in UTC) and how to consume it, while annotations carry the safety profile. Nothing an agent needs to invoke it correctly is missing.

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

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

Single parameter with 100% schema description coverage, so the schema already documents channelId and even points to postsider_list_channels as its source. The description only restates the channel scoping, adding no syntax or format detail beyond the schema, which matches the baseline-3 rule for high 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 verb (Return) and resource (the next free scheduling date-time in UTC) for a channel's posting queue. An agent can distinguish this from read siblings like postsider_list_channels or postsider_get_publishing_state because it returns a computed scheduling value rather than a 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?

Explicitly says to use the returned value as the `date` for postsider_create_post when scheduling into the queue, which is a strong workflow directive tying it to the correct sibling. It stops short of naming when NOT to use it or alternative slot sources, so it does not quite reach full when/when-not coverage.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds aggregation context (it pulls many resource types at once) and ties "recent errors" to the days window, but says nothing about permissions, cost, or freshness of the data.

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, purpose first and usage second, with no filler. The long enumeration of included sections is justified because no output schema exists to describe the return payload.

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

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

With no output schema, the description carries the burden of describing return content and does so by listing the aggregated sections, which is what makes this tool callable with confidence. It stops short of explaining the aggregation scope (all clients vs. filtered) or ordering, but nothing essential 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?

With a single parameter at 100% schema description coverage, the schema already explains that 'days' is the window for recent errors. The description mentions "recent errors" but adds no format, default, or boundary detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (Get) and resource (organization-wide operational overview for an agency) and enumerates the payload sections: clients, channels, queued posts, drafts, published posts, errors and pending approvals. It is clearly distinct from narrow siblings like get_customer_report or get_channel_analytics, though it never names an alternative explicitly.

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

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

"Useful for morning checks and client reporting" gives two concrete usage scenarios, so the agent can infer intent. However, there are no when-not conditions and no routing guidance versus sibling tools such as get_customer_report, leaving the choice of tool largely to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add context — which it does by disclosing the returned state vocabulary, including that a rejected status may carry the reviewer's note and that 'NONE' means approval was never requested. This resolves the main ambiguity for an agent. It does not discuss auth, rate limits, or latency, which are minor for a single-id read.

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 and result states, with the edge case ('NONE') placed last. No filler or restated boilerplate.

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?

This is a simple one-parameter read with no output schema, so the description must carry the return-value burden — and it does, spelling out the possible statuses and the never-submitted case. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, so postId is already documented. The description adds a small amount of meaning by implying the post should be one routed through the approval flow, but it gives no format or syntax guidance beyond the schema's blanket baseline.

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

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

The description names a specific verb ('Check') and resource ('a post's approval status') and enumerates the possible outcomes (approved, rejected with reviewer note, pending, NONE). It explicitly ties the tool to the sibling postsider_request_approval, so an agent can distinguish it from adjacent post tools like postsider_get_post or postsider_get_publishing_state.

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

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

It clearly places the tool in context: use it on a post that was submitted via postsider_request_approval, and it explains what a 'NONE' result means. It does not name an alternative tool or state exclusions, but the implied usage is unambiguous for this narrow lookup.

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 structurally. The description adds one genuinely useful behavioral fact beyond that — availability varies by provider — but says nothing about what is returned, rate limits, or auth requirements, and there is no output schema to fall back on.

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

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

A single front-loaded sentence with the resource first and the caveat trailing. No filler, no restatement of the title, and the provider caveat 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 simple two-parameter read with no output schema, the description omits what analytics are actually returned (metrics, granularity, date defaults), which the agent cannot recover from structured fields. The core call mechanics are clear enough, but the return contract is unstated.

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% with only two parameters, so the schema already documents that channelId comes from postsider_list_channels and that date is provider-specific. The description adds nothing beyond 'for a connected channel', so the baseline 3 applies.

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

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

States a specific verb and resource (get account-level analytics for a connected channel) and scopes it as 'account-level', which implicitly separates it from the post-level sibling postsider_get_post_analytics. It stops short of naming that sibling explicitly, so an agent still has to infer the boundary between the two analytics tools.

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 parenthetical '(where the provider supports it)' signals a precondition and implies usage is provider-dependent, which is real guidance. However, it never names an alternative tool, states when-not to use it, or explains what to do when the provider does not support 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower. The description adds genuinely useful context that the annotations cannot: the report is scoped to a single customer and returns categorized counts, which is the only disclosure of return content since no output schema exists.

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 with zero filler, front-loading the verb, scope and returned dimensions. Nothing repeats the title or name and every clause carries information.

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

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

With no output schema, the description usefully enumerates the report's count categories, and annotations cover the mutation/safety dimension. It is slightly thin on the relationship to sibling reporting tools and on whether counts are affected by any filters beyond 'days', but nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% — both 'days' (window for recent errors, max 365) and 'customerId' (from postsider_list_groups) are fully documented in the schema. The description adds no parameter-level syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get a customer-scoped agency report') and enumerates what the report contains (channel, queued, draft, published, error, pending approval counts). The 'customer-scoped' framing implicitly distinguishes it from postsider_get_agency_overview, but the sibling is never named, so the differentiation is left to inference.

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

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

The description implies the use case (pull per-customer counts for a report) through the field list, but never states when to prefer this over postsider_get_agency_overview or postsider_get_publishing_state, nor any prerequisites. Usage is inferable rather than stated.

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, non-destructive, and openWorld, so the safety profile is covered. The description adds useful substance by enumerating what notifications contain, but says nothing about recency window, result limits, read/unread state, or whether notifications are consumed on read.

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 front-loaded sentence with the core purpose first and examples in parentheses. No filler, no redundancy, nothing that fails to earn 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 zero-parameter, read-only list tool with no output schema and no required inputs, the description supplies the purpose plus representative content. It is nearly complete; only the recency/volume semantics of "recent" are left unspecified.

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

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

The tool takes zero parameters, so there is nothing parametric for the description to clarify; baseline 4 applies. The description correctly does not invent parameters or imply filtering options that do not exist.

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

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

States a specific verb and resource ("List recent notifications for the organization") and grounds it with concrete examples (publish failures, channels needing reconnection). It does not explicitly differentiate itself from siblings that may also surface alerts (get_agency_overview, get_customer_report), so it falls short of a 5.

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?

Usage is implied by "recent notifications" and the examples suggest it is the alert/status surface, but there is no explicit when-to-use, when-not-to-use, or named alternative among the numerous sibling tools. An agent can infer intent but gets no routing guidance.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, so the safety profile needs no restating. The description adds genuinely new behavioral context: the async create/publish workflow this read supports and the fact that publish errors surface in the response, implying polling semantics.

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 resource and return contents, then the usage trigger. No filler and no restatement of the title.

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

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

With no output schema, the description usefully enumerates the returned fields, and annotations cover the safety profile. The only gap is not clarifying its boundary against overlapping siblings like get_publishing_state and get_post_missing_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?

Schema description coverage is 100% and the schema already says postId is 'returned by postsider_create_post.' The description adds no additional syntax, format, or sourcing detail for the single required parameter, 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 (organization-scoped post group) and enumerates exactly what is returned: current state, scheduled time, media, channel, publish error. This differentiates it from analytics/missing-fields siblings by content, though it does not explicitly name the near-neighbors such as postsider_get_publishing_state.

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

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

Gives an explicit trigger phrase: 'Use this to inspect the result of an asynchronous create or publish operation.' That clearly routes an agent here after create/publish, but no alternatives or exclusions are named for related read 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety behavior needs no restating. The description does add one genuinely useful behavioral fact beyond the annotations: the tool is provider-dependent ('where the provider supports it'). It says nothing about rate limits or what the returned metrics contain.

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, front-loaded sentence with zero filler; the resource, scope, and the provider caveat are all packed in without padding.

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

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

There is no output schema, so the description could have indicated what 'performance analytics' actually returns (impressions, engagement, etc.); it does not. Annotations and full schema coverage carry most of the burden, but for an analytics tool the return-content gap keeps this at minimum viable.

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% with only two parameters, both documented in the schema (including the default of 7 and the exclusive minimum for 'days'), so the baseline is 3. The phrase 'last N days' loosely restates the 'days' parameter but adds no format or boundary detail 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 states a specific verb and resource ('Get performance analytics for a single post') and scopes it by a look-back window, which clearly distinguishes it from the channel-wide sibling 'postsider_get_channel_analytics'. It stops just short of naming that sibling explicitly, so sibling differentiation is only implied by the word 'single post'.

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

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

Usage is implied rather than stated: an agent can infer this is the per-post counterpart to channel analytics, and the caveat 'where the provider supports it' signals a conditional availability. There is no explicit when-to-use/when-not-to-use guidance and no alternative tool is named.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the per-channel granularity of the result set, which is genuine value, but says nothing about return format, ordering, or whether validation is live versus cached.

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?

One sentence, front-loaded with the action and resource, with the purpose clause last. Nothing is wasted and nothing needs to be cut.

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

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

There is no output schema, so the description carries the burden of signalling return content, and it does so reasonably ('per-channel validation problems / missing required fields'). For a one-parameter read tool this is nearly sufficient, though it does not describe the shape or severity semantics of the problems returned.

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% with a single postId parameter already documented in the schema. The description adds no syntax, format, or scoping detail about postId, so the schema does all the work — baseline 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 states a specific verb and resource: it returns per-channel validation problems and missing required fields for a post. That is clearly distinct from a plain postsider_get_post, though it never names or contrasts with any sibling tool.

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 trailing clause 'so they can be fixed before publishing' implies the pre-publish validation workflow, which is useful context. However, there is no explicit when-to-use vs alternatives (e.g., get_post, get_publishing_state) and no stated prerequisites.

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/idempotent/non-destructive, and the description adds genuinely new behavioral context: a paused org rejects new posts with the error code publishing_paused. It doesn't describe the exact response shape beyond 'active or paused', but the error-code disclosure is real added value.

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 tight sentences, front-loaded with the core question and then the motivating use cases. Nothing is wasted.

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

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

No output schema exists, so the description must carry return semantics; 'active or paused' conveys the essential value but not the exact field/format an agent would receive. For a zero-param read tool, this is nearly complete.

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

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

Zero parameters, so the baseline is 4. The phrase 'for this organization' usefully clarifies that the org scope is implicit rather than passed in.

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: 'Check whether publishing is active or paused for this organization.' It is unmistakably distinct from the sibling pause_publishing and get_post_* tools.

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

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

Gives concrete usage context (check before scheduling, confirm a kill switch is on) and cites the failure mode publishing_paused. It does not explicitly name pause_publishing as the mutation counterpart or state when *not* to bother calling, so it falls just 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, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds only the org-scoping detail and the returned field set; it says nothing about pagination, empty results, or rate limits, so it is modestly additive rather than 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, no filler, with the primary purpose front-loaded and the usage pointer second. Every clause carries information.

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

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

With zero parameters and no output schema, the description fully compensates by naming the returned fields (id, name, platform) and the ordering constraint relative to postsider_create_post. An agent has everything needed to call 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 tool takes zero parameters, which is the baseline-4 case. The description correctly implies no filtering arguments are needed, though there is no parameter nuance to explain.

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

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

States a specific verb and resource ('List the social channels (integrations)') and further pins down the scope ('connected to this PostSider organization') plus the returned fields (id, name, platform). It is clearly distinguishable from neighboring list/analytic tools like postsider_list_groups and postsider_get_channel_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?

Explicitly routes the agent: 'Call this first to get the channel ids needed by postsider_create_post,' which names the downstream dependency and the reason to invoke it. It lacks any when-not guidance or alternatives among the other list tools, 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds value beyond them by disclosing the return semantics — that the ids returned are usable as customerId elsewhere — which matters because there is no output schema. Pagination or result-size behavior is still undisclosed.

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, both front-loaded and earning their place: the first gives the action, the second gives the semantic mapping and the downstream routing. No filler or repetition of the title.

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

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

For a zero-parameter, read-only list tool with no output schema, the definition covers what it returns, what the identifiers mean, and where to use them next. Nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to compensate for. Schema coverage is 100% and the empty object schema is unambiguous.

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

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

States a specific verb and resource ("List configured channel groups") and immediately disambiguates a domain term that would otherwise confuse the agent: a group is a customer in PostSider. This distinguishes it from siblings like postsider_list_channels and postsider_list_posts without opening any schema.

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

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

It names the concrete consumers of the returned ids (postsider_get_customer_report and the customer filter of postsider_list_posts), which effectively tells the agent why and when to call this first. It does not state exclusions or when-not-to-use, so it falls short of a full 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, covering the safety and mutability profile. The description adds the UTC timezone constraint and the status scope ('scheduled or published'), which is useful context beyond annotations. However, it does not disclose pagination, result ordering, or limits; with annotations covering safety, a 3 is appropriate.

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

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

Two concise sentences with zero waste. The core scope (date range, statuses) is front-loaded, followed by the usage hint.

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

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

Given a simple 3-parameter read-only list tool with no output schema and full schema coverage, the description covers purpose, scope, and a usage hint. It could be improved by noting pagination or return format, but for this complexity level it is sufficient.

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 all parameters are documented in the schema. The description confirms the date range and UTC basis but adds no syntax or format details beyond what the schema provides. Baseline 3 when schema does the heavy lifting.

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

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

States a specific verb+resource: lists posts, constrained to scheduled or published status within a date range. This is clear. However, it does not differentiate from siblings like postsider_get_post or postsider_find_slot beyond the implicit list-vs-single distinction; a more explicit contrast would earn a 5.

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?

Offers implicit usage guidance: 'Useful for reviewing the content calendar before scheduling more.' This suggests a context but does not say when to use it versus alternatives, nor does it name siblings or state 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?

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true), which already flag the operation as a risky write. The description discloses the exact blast radius — no `now`/`schedule` posts can be created and queued posts are parked to HELD rather than sent — plus the irreversible, API-unresolvable resume path.

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

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

Three tight sentences, front-loaded with the highest-stakes information (immediate halt, kill switch) before triggers and the irreversibility caveat. No redundant restatement of the name or title.

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

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

For a destructive, org-wide switch with no output schema, the description covers scope, side effects, triggers, and recovery constraints well. It does not say what the call returns or whether a confirmation/response object indicates the paused state, which is the only remaining gap.

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

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

Schema description coverage is 100% and the single optional `reason` parameter is fully documented in the schema as recorded in the audit trail. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Immediately halt ALL publishing for this organization') plus the kill-switch scope, which cleanly distinguishes it from the read-only sibling postsider_get_publishing_state. An agent can identify the operation without opening the schema.

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

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

Gives concrete trigger conditions ('when something is wrong, for example a PR crisis, a post on the wrong channel, or a runaway automation loop') and a clear when-not for recovery ('Resume is human-only (owner, dashboard); this cannot be undone via the API'). It stops short of naming the sibling to inspect state first (postsider_get_publishing_state), so it is clear context rather than fully explicit alternatives.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description doesn't need to re-state them. It does add useful behavioral context: this routes a post into a human review workflow rather than publishing it, and requires an existing draft. It stops short of saying what happens to the post's status or whether the request can be withdrawn.

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

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

Three sentences, each carrying information: the action, the prerequisite, and the optionality of the whole flow. No filler, and the core purpose is front-loaded in the first sentence.

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

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

For a single-parameter mutation with full schema coverage and no output schema, the description supplies the workflow context an agent needs: draft precondition, queue destination, and that this path is optional. Minor gaps remain around permissions/authorization and what happens to the draft's status after submission.

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

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

Schema coverage is 100% and the single postId parameter is already documented as 'Draft post id to submit for approval.' The description reinforces that the post must already be a draft, which adds a mild constraint beyond the schema, but no format or id-source detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

Specific verb and resource: pushes a draft post into the human approval queue. It explicitly contrasts the action with the alternatives (publishing or scheduling directly), so an agent can distinguish it from siblings like postsider_update_post_status or postsider_create_post.

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

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

States the prerequisite (post must already exist as a draft, with a pointer to postsider_create_post with type "draft") and names the alternatives it replaces. It also flags that approval is optional and most posts can be scheduled directly, giving the agent a clear when-not-to-use signal.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and repeatability profile is carried structurally. The description adds only that the post must already exist; it says nothing about permissions, validation failures, or what happens when an invalid transition is attempted.

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?

One short sentence with the action front-loaded and no filler, which is appropriate for a simple setter. The parenthetical example is the only questionable use of space given it uses the wrong enum label.

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

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

For a two-parameter mutation with rich annotations and no output schema, the description is minimally adequate: the agent knows what it changes and on what. It omits any mention of valid transitions, error behavior, or prerequisites, and the queue/schedule mismatch leaves a gap the schema alone must resolve.

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 both parameters documented, including the enum, so the schema is authoritative and the baseline is 3. The description's 'queue' wording actually conflicts with the schema's 'schedule' value, so it adds no reliable meaning beyond the schema and slightly muddies it.

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

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

States a specific verb (change status) and resource (an existing post), and the parenthetical clarifies it is a state transition rather than a content edit, which separates it from create_post/delete_post/get_post. However, the example term 'queue' does not match the actual enum values (draft/schedule), introducing a small ambiguity about what states exist.

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 no when-to-use guidance and names no alternatives, even though siblings like request_approval, pause_publishing, and get_publishing_state are plausible confusions. The agent must infer from the tool name alone that this is the setter for post status.

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

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

Annotations already declare the write (readOnlyHint=false), external reach (openWorldHint=true) and non-idempotency. The description adds meaningful context beyond them: the source must be a public URL, and the result is a persisted media object in the library that can be chained into post creation. It omits size/type limits and duplicate-on-repeat behavior, so not a 5.

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

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

Two tight sentences: purpose first, downstream chaining second. No filler, no restating the tool name.

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

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

With no output schema, the description correctly summarizes the return value (a media object) and how to use it, which is what an agent needs for this single-parameter import. Minor gaps on limits and repeat-call behavior keep it from a 5.

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

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

Only one parameter and schema coverage is 100%, and the schema already documents it as a 'Public HTTPS URL of the image or video to import.' The description repeats the 'public URL' idea without adding syntax, size, or format guidance, so it meets the baseline but adds no new meaning.

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

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

States a specific verb (download/store) and resource (image or video media into the PostSider media library) and clearly separates this import action from sibling tools like postsider_create_post or the list/get tools. An agent knows this is a URL-to-library ingest, not a post creation.

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 forward-looking usage context by naming the downstream step: pass the returned media object (or array) as `images` to postsider_create_post. It does not state when not to use it (e.g., local file upload path) or the public-URL-only restriction as an exclusion, but the triggering condition is clear.

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