postnext

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

Annotations cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds real behavioral context beyond them: the response echoes the block 'AS STORED' so rejected fields are visibly absent, the concrete idempotency trigger, and the non-obvious rule that phase is a no-op until a dashboard campaign 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?

It is long, but every clause is load-bearing given 35 parameters and zero schema descriptions. The core purpose is front-loaded, followed by the type/required-field reference, then the idempotency and phase caveats. No obvious filler sentences, though the type list and required-field block are dense 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?

An output schema exists, so return-value explanation is not required, yet the description usefully clarifies echo-as-stored semantics and the campaign prerequisite. It does not mention which parameter identifies the target site (siteId is not required in the schema), which for a 35-param tool is a small 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 0%, so the description carries the burden, and it does the highest-value work: it maps required fields per type (url, title+startDate, provider+url, timezone+days, embedUrl constraints, etc.) and the http(s) URL rule. Many optional params (order, limit, price shape, alt, caption, label, artworkUrl, visibleFrom/Until, postReleaseLinks) remain undocumented, so it compensates well but not completely.

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

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

Opens with a specific verb+resource: 'Add one block to a bio page.' It then enumerates the block types, which immediately separates it from update_mini_site_block, remove_mini_site_block, and get_mini_site in the sibling list without the agent needing to open another 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 strong conditional guidance for the phase field (when 'before'/'after'/'always' apply) and an explicit prerequisite: check get_mini_site.campaign and warn the user if null. It also discloses the idempotency branch (same type+url returns existing block). It stops short of explicitly routing the agent to update_mini_site_block for existing blocks, so it is not a full when-not statement.

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 idempotentHint=true and destructiveHint=false, and the description adds useful specifics beyond them: the draft is preserved rather than deleted, and the idempotency is contextualized as 'safe to call on already-cancelled posts.' It doesn't describe the queue side effects or failure modes, but the safety-relevant behavior is well covered.

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 with the primary action front-loaded and each clause carrying distinct information (queue removal, draft preservation, idempotency). No waste.

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 an output schema present and annotations covering the safety profile, the description covers the essential behavioral facts. The only gap is the undocumented postId, which the output schema and annotations cannot fill in.

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 0% and the required postId is never mentioned in the description, so no format or sourcing guidance is added. postId is fairly self-explanatory by name, but the description does nothing to compensate for the schema gap.

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 ('Cancel a scheduled post') plus the effect ('remove it from the publish queue'), which distinguishes it from schedule_post and delete_draft. 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?

The parenthetical 'The draft is preserved (not deleted)' implicitly routes the agent away from delete_draft when the draft should survive, giving clear usage context. It stops short of explicitly naming alternatives or stating when-not-to-use.

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

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

Annotations cover the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds behavior the annotations cannot express: the URL is one-time-use and requires a human to open it in a browser and authorize. It stops short of stating URL expiry or the post-authorization flow, but the human-in-the-loop disclosure is genuinely additive.

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

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

Two sentences, front-loaded with the core action, no filler. Every clause earns its place by telling the agent what is produced and what the user must do with 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?

An output schema exists, so return values need not be explained, and the description correctly focuses on the action and the browser handoff. It is slightly incomplete in not indicating what the agent should do after authorization (e.g., check list_connected_accounts) or how long the one-time URL remains valid.

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 'platform' parameter has 0% schema description coverage, and the description never mentions it or explains which platforms are supported. The enum in the schema enumerates the valid values, which carries most of the semantic load, but the description contributes nothing beyond that.

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 (generate) and a specific artifact (one-time authorization URL) for connecting a social channel. An agent can distinguish this immediately from siblings like list_connected_accounts or test_blog_connection, which do not produce a connection URL.

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 usage flow by stating the user must open the URL in a browser and authorize, which tells the agent this is a human-in-the-loop step rather than a silent backend call. However, it never names when to prefer this over alternatives or what prerequisite state (e.g., being in the right team/workspace) is 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?

Goes well beyond the annotations by disclosing the asynchronous generation model and immediate "generating" return status, the paid-tier requirement, and critically the auto-publish side effect on Business/Teams with the autoPublish:false escape hatch. This warns of a consequence the structured fields alone would not reveal.

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

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

Front-loads the core purpose and async behavior, then adds tier and parameter detail. Dense but each sentence carries distinct information; the auto-publish note is appropriately emphasized rather than buried.

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

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

With an output schema present, return-value explanation is unnecessary, and the description covers the important behavioral context (async, tiers, auto-publish). The gap is undocumented parameters for the required startDate and several optional fields, which keeps it from being 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?

Schema description coverage is 0%, so the description must carry parameter meaning. It documents three of eight (brandProfileId default, integrationId default, autoPublish false=keep drafts) but leaves the required startDate and planDays, timezone, contentLanguage, competitorDomains unexplained. Partial compensation only.

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 ("Create a blog content plan (the Post Planner) for a brand profile"), which distinguishes it from siblings like create_post_draft and list_blog_plans. The parenthetical naming plus brand-profile scoping makes the target 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 clear operational context: the plan returns immediately in status "generating" and the agent should poll list_blog_plans for progress. It also explains the tier gating (Basic+) and defaults for brandProfileId/integrationId. It stops short of explicitly contrasting when to use this vs create_post_draft, so it's a strong 4 rather than a 5.

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

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

Goes well beyond the annotations: it discloses that drafts are not auto-published, the 5-minute idempotency window (expanding on idempotentHint), per-platform content limits, alt-text handling per platform, and the dashboardUrl return. This is meaningful operational context an agent cannot get from the structured fields.

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?

Heavily front-loaded with the key constraint (drafts not auto-published) before parameter detail, and every sentence carries distinct information. It is dense and reads as one long block with many semicolons, which slightly hurts scannability, but little 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?

Given a 9-parameter tool with 0% schema descriptions, an output schema, and annotations covering the safety profile, the description covers all parameters, the draft semantics, idempotency, and even the return value. 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 0%, so the description must carry the full load, and it does: threadParts (2-25 items, per-post limits), channelName vs providerId semantics, clientRequestId idempotency, instagramTrialReel values, media object shape with alt/type, and platform-specific alt-text limits. Excellent compensation for the coverage gap.

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 (Create a new draft post) plus platform scope, and clearly distinguishes itself from siblings: it names list_connected_accounts as a prerequisite helper and frames drafts as non-publishing, implicitly routing to schedule_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?

Rich conditional routing is provided for parameters (threadParts vs content, channelName vs providerId, instagramTrialReel conditions, media vs mediaUrls). It names list_connected_accounts to call first, but never explicitly contrasts this tool with siblings like schedule_post or update_post_draft for the 'when-not' side.

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 and readOnlyHint=false, and the description usefully reinforces that the delete is permanent and adds the non-obvious guardrail that scheduled/published posts are rejected. It does not say what error surfaces on refusal, whether the draft is recoverable, or address the idempotency behavior implied by idempotentHint=false, so it stops short of full behavioral coverage.

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

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

Two short sentences, no filler; the destructive scope is front-loaded and the guardrail/alternative follows immediately.

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

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

An output schema exists so return values need no explanation, and annotations carry the safety profile. The description covers the key refusal case; only minor details (auth requirements, failure behavior) are absent.

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 0% and the description adds no information about postId (format, source, whether it must be an existing draft). The name is largely self-explanatory and there is only one parameter, so this gap is minor, but per the low-coverage rule the description does not compensate.

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

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

Specific verb + resource ("Permanently delete a draft post") with an explicit scope limit that separates it from cancel_scheduled_post. An agent can pick this over the many post-related siblings without opening any schema.

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

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

Gives both the when-not (scheduled or published posts are refused) and the named alternative (cancel_scheduled_post) that should be used instead. This is exactly the routing information an agent needs when it has a post ID and is unsure which mutating tool to call.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new context beyond the annotations: the paid-plan prerequisite, which affects whether the call is even permitted. It stops short of disclosing cost/rate behavior or whether results are cached/fresh.

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: the first front-loads the verb and the exact contents of the summary, the second carries the two operational constraints. No filler and nothing buried.

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

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

An output schema and annotations exist, so return shapes and safety need not be restated. Purpose, platform filtering, and the plan gate are all present; the only material omission is any explanation of the windowDays parameter, which leaves the agent guessing about the aggregation window.

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

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

Schema description coverage is 0%, so the description has to carry both parameters. It covers platform ('Optionally filter by platform') but never mentions windowDays, and the phrase 'next 7 days' refers to token expiry rather than that parameter's 7/30/90 enum with a default of 30 — so half the parameters remain semantically unclarified.

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 (get) plus well-defined resource (account-health summary) with an enumerated payload: connected-account counts, scheduled/published/failed post counts, draft count, and expiring tokens. This is clearly distinguishable from siblings like get_channel_analytics and list_connected_accounts, which return different scopes.

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 two usable conditions: the output can be narrowed with an optional platform filter, and the tool requires a paid plan, which is a real gating prerequisite. It does not, however, contrast itself with near-neighbors such as get_channel_analytics or get_plan_limits, so the agent must infer when this summary is preferred over those.

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 cover readOnlyHint and openWorldHint. The description adds substantial behavioral context: the 90-day lookback window, the fact that ranking methodology differs by platform (engagement-weighted vs post-frequency for LinkedIn/Threads/TikTok with 'engagement collection deferred'), timezone defaults, and the paid-plan gate. This exceeds what structured fields 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?

Three sentences covering purpose, per-platform behavior, timezone, and plan requirement. Front-loaded with the core purpose, no filler, every sentence earns its place.

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

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

With an output schema present, the description needn't detail return values. It covers purpose, platform-specific behavior, timezone handling, and plan gating. The one gap is explaining the topN parameter, which is relevant since the description mentions ranked slots but not the count control.

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 0%, so the description must compensate. It explains that platform determines ranking methodology and that timezone is IANA-format with a UTC default. It does not describe the topN parameter, which is a gap, but the two most semantically rich parameters are covered.

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 ('Recommend the best (dayOfWeek, hour) slots') with precise scope: 'for the user's next post on a given platform, ranked by engagement-per-post over the past 90 days.' This is clearly distinguishable from siblings like get_channel_analytics or get_post_metrics.

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

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

The description makes clear when to use it (scheduling the next post, per platform) and states a hard prerequisite ('Paid plan required'). However, it doesn't name alternative tools or explicitly say when not to use it versus get_channel_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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: the omit-platform default (team-wide total), the fact that providerId survives a handle change, and the 30d period default.

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

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

Dense but front-loaded: the capability statement leads, scoping rules follow, and usage routing anchors the end. Every sentence adds information, though the run-on scoping sentence slightly reduces readability.

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

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

With an output schema present, return values needn't be described, and all parameters, defaults, and usage conditions are covered. An agent has everything needed to call this 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 coverage is 0%, so the description carries the full burden and does so well: it explains that omitting platform yields a team-wide total, that channelName/providerId scope a platform with multiple accounts, that providerId persists across handle changes, and it enumerates period values and the default. Minor gap is that channelName vs providerId selection logic could be sharper.

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 (aggregate performance) and resource (one connected channel or all channels), and explicitly distinguishes itself from get_post_metrics and get_best_time_to_post. An agent can route between these without opening a schema.

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

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

Gives explicit when-to-use conditions (team-wide vs single-channel, how to scope by platform/channelName/providerId) and names the alternative tools with their distinct purposes. Nothing is left 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the 'Read-only' clause is partly redundant. However the description adds genuinely new behavioral context: zero credit cost, that the integration summary contains 'no secrets', and the shape of the returned post data. That is useful beyond the annotations, though not exhaustive about failure modes (e.g. behavior when no blog is connected).

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?

Roughly three dense sentences that are front-loaded with the return contract, then the routing guidance. Slight redundancy in restating read-only behavior that annotations already cover, but no filler.

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

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

The tool is low-complexity with zero parameters and an output schema, so return values need not be enumerated. The description nonetheless summarizes the key outputs and states the credit/auth implications, which is complete enough for an agent to call it correctly on the first try.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the schema-level baseline of 4 applies. The description correctly implies a no-argument call by describing only team-scoped output.

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 compound verb+resource: check WordPress blog connection and fetch the latest post snippet. It clearly separates this from siblings like test_blog_connection and create_blog_plan by naming what it returns (blogConnected, integration summary, latest post title/snippet/status/URL).

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 an explicit precondition: 'Use before create_blog_plan or test_blog_connection to see if a blog is wired up and what was last published.' Both the alternative tools and the selecting condition are named, leaving nothing 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 only cover safety (readOnlyHint=true, openWorldHint=false), while the description adds substantive behavior: 300-character truncation of long text blocks, explicit exclusions (email-sync credentials, tracking pixel IDs), and the meaning of suspended: true plus the remediation path and support contact. This is exactly the kind of context annotations cannot convey.

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

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

Three dense sentences, front-loaded with what is returned before the parameter rule and the suspension caveat. Every clause carries information, though the long enumeration of content-block types is slightly heavier than needed.

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

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

An output schema exists, so return-value structure is already covered, yet the description still flags the two things a schema cannot express: truncation of long text and withheld fields. Combined with the suspended-state semantics and the siteId omission rule, an agent has everything needed to call and interpret this tool.

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

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

The single siteId parameter has 0% schema description coverage, so the description must compensate, and it does: it explains when siteId may be omitted entirely (single-site teams). It stops short of stating the expected ID format or where to obtain one, which list_mini_sites presumably supplies.

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 ('Read one bio page in full') and then enumerates the actual contents returned: profile header, social icons, content blocks, SEO metadata, theme and auto-pin settings. An agent can immediately distinguish this single-site read from the sibling list_mini_sites.

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 a concrete selection rule for the optional parameter: 'Omit siteId when the team has exactly one site.' It also implicitly scopes the tool to reading one page versus listing many, but it never names list_mini_sites or get_mini_site_analytics as alternatives, so the routing guidance is clear but not exhaustive.

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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a genuinely important behavioral nuance beyond annotations: almost every figure is an all-time counter, not windowed, and the agent should say so when reporting — a subtle trait that prevents misreporting. It does not mention rate limits or pagination, so it stops short of a 5.

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

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

Three tight sentences, front-loaded with what the tool returns before the caveats. The parenthetical 'say so when reporting numbers' is arguably dispensable but carries real reporting guidance, so it earns its place. Slightly dense but no wasted 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?

An output schema exists, so the description needn't explain return structure; instead it focuses on the two things an agent must know — the lifetime-vs-windowed caveat and the siteId omission rule. For a two-parameter read tool with a full output schema, nothing material 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 0% schema description coverage, the description compensates well: it explains that siteId can be omitted when there is a single site, and clarifies that attributionDays governs the 'configurable recent window' that applies only to attribution rows. It doesn't restate the default (30) or maximum (90) that the schema already defines, but the added semantic meaning is substantial.

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 the specific resource (a bio page / mini site) and enumerates the exact metrics returned — views, clicks, best-performing links, source/device/country, AI-crawler reads, and post-to-click attribution. This is clearly distinct from sibling analytics tools like get_channel_analytics or get_post_metrics. An agent can identify the tool's scope without opening the schema.

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

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

It gives actionable usage context: 'Omit siteId when the team has exactly one site' and warns that attribution is windowed while other figures are lifetime. However, it never explicitly says when to prefer this tool over alternatives such as get_channel_analytics, leaving sibling selection 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the scoping note that this tool is 'purely about plan identity and billing dates,' which is useful but not a new behavioral trait; it says nothing about auth requirements, staleness/caching of billing dates, or failure modes.

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, front-loaded with what is returned, then when to call it, then the disambiguation. Every sentence carries distinct information; nothing is redundant with the title or annotations.

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

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

With an output schema present, return values need no prose explanation, and the description still usefully previews the fields. For a zero-parameter, read-only tool with full annotation coverage, 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?

The tool takes zero parameters, so the baseline is 4 per the rubric. The schema carries no argument semantics for the description to explain or compensate for.

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 ('Return the user's plan + billing-date info') and enumerates the exact payload: tier, renewal date, trial end date, cancel-at-period-end state. It explicitly separates itself from the sibling get_plan_limits, so an agent can route correctly without opening either schema.

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

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

Gives concrete trigger phrasing ('when does my plan renew?', 'how many days left on my trial?', 'is my subscription cancelling?') and names the alternative tool plus the condition that selects it ('for quotas and usage... call get_plan_limits instead'). When-to-use and when-not-to-use are both explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is fully covered by structured data. The description adds one genuine behavioral fact beyond that — 'Available on every plan (no AI credit cost)' — which tells the agent this call is free even on metered plans. Beyond that single note it adds no other runtime context, so it is a moderate rather than rich contribution.

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 return payload first, then availability/cost, then usage triggers. Dense and largely waste-free, though the final sentence is a long parenthetical chain of three pre-check examples that could be trimmed without losing meaning.

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

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

An output schema exists, so return values need not be explained, yet the description still previews the key quota dimensions. Combined with zero params and full annotation coverage, nothing an agent needs to invoke 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?

The tool takes zero parameters, so the baseline is 4 and there is no syntax or format information the description needs to supply. The phrase 'the user's current' correctly conveys that the scope is implicit rather than parameterized.

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 (return current subscription tier and per-tier quotas) and enumerates the quota categories returned: channels, storage, AI credits, posting. That is clear enough for selection, though it never distinguishes itself from the sibling get_plan, which an agent could easily confuse it with.

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

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

Explicitly says when to call (user asks about plan or limits) and when to call proactively, naming concrete trigger conditions and the exact sibling operations involved (create_post_draft with low aiCalls, schedule_post on FREE, connect_channel near the channel cap). This is the strongest possible 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds valuable context about what is returned: 'full provider-by-platform content map plus status, timestamps, and dashboardUrl', which is beyond the annotations.

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

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

Two concise sentences, front-loaded with the core action and followed by return details. Every sentence adds value with no repetition.

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

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

The tool has an output schema, so the description needn't detail return values, but it helpfully mentions key fields. It lacks guidance on error cases (e.g., invalid postId) or permissions, but overall is complete for a simple getter.

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

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

Schema description coverage is 0%, so the description must compensate. It documents only that the parameter is a 'postId' and what it refers to, adding minimal semantics beyond the schema. Since the parameter name is self-explanatory and there's only one required string, the description's brief mention is adequate but not enriching.

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: 'Fetch a single post (draft or scheduled) by its postId.' The scope qualifier 'draft or scheduled' distinguishes it from list_drafts and list_scheduled_posts.

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

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

The mention of 'draft or scheduled' implies retrieval of any post state, but the description doesn't explicitly say when to use get_post versus search_posts or list_drafts. Usage context is implied but not 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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: metrics are populated for Twitter/Instagram but only publish status + URL are returned for LinkedIn/Threads/TikTok, which prevents misreading empty metrics as zero engagement. Auth, rate limits, and error behavior remain undescribed.

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, zero waste, with the core action front-loaded and the platform-coverage caveat following. Both sentences carry load: the first defines the tool, the second prevents a misinterpretation of the output.

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

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

An output schema exists, so return-value structure need not be re-explained, and the description instead supplies the one thing that matters most for correct interpretation: which platforms actually return engagement data. For a single-required-param read tool, this is 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?

Schema description coverage is 0% and the single postId parameter carries no description, so the schema does not explain it. The name 'postId' is fairly self-describing, but the description adds nothing about expected format, where to obtain the ID, or validity constraints, so the description does not compensate for the coverage gap.

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 (Fetch) + resource (engagement metrics: likes, comments, shares, impressions) + scope (a published post across every platform it was sent to). This clearly distinguishes it from get_post, get_publish_status, and get_channel_analytics, which an agent can tell apart 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?

The 'for a published post' framing and the per-platform return caveat give a clear sense of when this tool is appropriate versus draft-facing tools. However, it never names an explicit alternative (e.g. get_channel_analytics) or an exclusion, so the routing is implied 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the remaining burden is light. The description adds a genuine behavioral quirk: isScheduled=false for drafts that were never queued, which an agent cannot infer from schema or 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?

Three sentences, front-loaded with the diagnostic purpose, then usage examples, then an edge-case caveat. No padding; each sentence carries distinct information.

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

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

With an output schema present, return-value explanation is not required, and the description still adds the draft/queue edge case. The only gap is routing guidance relative to siblings such as get_post.

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

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

Schema description coverage is 0% and the description says nothing about postId's expected format or source. The name itself is largely self-explanatory (a post identifier), so the gap is moderate rather than severe, but the description adds no meaning 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?

States a specific verb+resource ('Diagnose what happened to a scheduled post') and enumerates the exact facets returned (queue/publish state, per-platform success/error, worker processing time). This clearly separates it from siblings like list_scheduled_posts (listing) and get_post (content retrieval).

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 concrete trigger scenarios in user-voice ('did my post go out?', 'why did Tuesday's post fail on LinkedIn?'), which gives an agent an explicit when-to-use signal. It does not name alternatives (e.g. get_post for drafts) or exclusions, so it falls 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?

Beyond the readOnlyHint annotation, it adds meaningful behavioral context: "no credit cost", newest-first ordering, and the shape of what comes back (status, per-status topic counts, credit-reservation info, dashboard link). It does not cover pagination behavior for the limit cap, which is a minor gap.

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, front-loaded with purpose, then constraints, then usage. The return-value enumeration is slightly dense but each element is informative, so it stays efficient.

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

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

For a read-only list tool with an output schema available, the description covers purpose, ordering, filter options, cost profile, and usage intent. Nothing an agent needs to select or 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 0%, so the description carries the burden. It documents the status filter and enumerates the allowed values (though these duplicate the enum), but the limit parameter and its default/max bounds are never mentioned. Partial compensation warrants a mid 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 names a specific verb and resource ("List the team's blog plans") and clarifies the product surface with the alias "Post Planner". It is easily distinguished from siblings like create_blog_plan and get_plan, and states ordering ("newest first").

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

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

It gives explicit when-to-use guidance: check existing plans before creating a new one, or to monitor generation progress. It does not explicitly name the alternative get_plan for single-plan lookups, so the routing is clear but not fully comparative.

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

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

readOnlyHint already declares this a safe read, and the output schema covers return shape. Beyond that, the description adds a genuinely useful behavioral fact: providerId is stable when a handle changes, making it the durable key. That is real value beyond structured fields.

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 with zero filler. The core purpose is front-loaded and the downstream hand-off detail follows logically.

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 a 0-parameter schema, full description coverage, and an output schema handling return values, an agent has everything needed. The description correctly focuses on scope and the key stable identifier rather than restating outputs.

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. The description adds no parameter detail because there is none to add; it instead clarifies how the output's fields should be reused downstream.

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 with scope: 'List the social accounts connected to the user's team.' An agent can immediately tell this apart from connect_channel or the draft/post tools in the sibling set.

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 clear downstream context: the returned providerId should be passed to create_post_draft and get_channel_analytics, which tells the agent why to call this first. It stops short of explicit when-not guidance or contrasting with connect_channel/list_teams, so it is not 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 already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful scoping fact that only unscheduled drafts are returned, but says nothing about pagination, ordering, or how the limit interacts with a large draft list.

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

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

The purpose is front-loaded in the first clause and the description is only two sentences. The second sentence is long and packs several backticked field names, but every element is relevant to using the tool.

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

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

An output schema exists, so the enumeration of platforms/channelNames/content/dashboardUrl is largely redundant, though the client-side filtering hint is genuinely additive. For a simple read tool with annotations, this is adequate but leaves the only input parameter fully 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?

Schema description coverage is 0% and the single `limit` parameter (default 20, max 100) is never mentioned in the description, so its meaning and pagination behavior are undocumented in both places. The field-level detail provided is about response fields, not input parameters, so it does not compensate for the gap.

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 user's draft posts') and scopes it with '(not yet scheduled)', which implicitly separates it from list_scheduled_posts. It never names a sibling tool explicitly, so the differentiation is inferential rather than stated.

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 one concrete usage instruction: filter client-side via platforms/channelNames when the caller wants a specific platform or account. It offers no guidance on when to prefer this over get_post, search_posts, or list_scheduled_posts, and no exclusions or 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 establish the safe read-only, closed-world profile, but the description goes further with a domain-specific rule: suspended: true means PostNext took the page offline and it cannot be republished until support reviews it. That is real behavioral context an agent could not infer from the schema or 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?

Three sentences, front-loaded with purpose, then usage routing, then the suspended-state caveat. No redundancy and no filler; each sentence carries distinct information.

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

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

An output schema exists so return values need not be enumerated, yet the description still names the key fields and the one field (suspended) whose semantics are non-obvious. Combined with the routing guidance, an agent has everything needed to select and 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 no parameters, so there is no argument syntax to clarify; the description instead explains the implicit team scope of the result set. The 0-parameter baseline applies, and the team-scoping note is a small positive addition.

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 (List) and resource (bio pages / mini sites) scoped to the currently selected team, and enumerates what each entry carries (public URL, publish state, setup progress). This clearly distinguishes it from the single-site sibling get_mini_site.

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 call it first when the user mentions "my bio page", "link in bio" or "mini site", and explains the downstream contract: every other mini-site tool consumes the siteId returned here, which may be omitted when the team has exactly one site. Nothing is left 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 establish readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real behavioral detail beyond that: it joins ScheduledPost with PostGroup, injects content preview and channelName, caps results at `limit`, and orders by scheduledAt ascending.

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 with no filler, front-loaded with the core definition and followed by join/return behavior. Only minor redundancy in re-stating 'scheduled' twice.

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

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

With an output schema present, the description need not detail return shapes, and annotations handle the safety profile. The join/ordering/cap details make it largely complete, with the sole gap being the unexplained `from` filter.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains `limit` behavior (caps returned rows) but says nothing about `from`, leaving the date-time filter's semantics (inclusive? on scheduledAt?) entirely undefined for the caller.

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 (List) and resource (scheduled posts) and immediately disambiguates with the parenthetical '(queued for publish, not yet sent)', which cleanly separates it from siblings like list_drafts and search_posts.

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

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

It implies usage context by noting the caller can 'filter by handle client-side', which signals this tool does not filter by channel, but it never explicitly states when to choose this over list_drafts, get_post, or search_posts, nor any 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 only declare readOnlyHint=true and openWorldHint=false; the description adds the non-obvious membership scope (owner/admin only) and that one entry is flagged as currently active. It does not discuss the return shape or empty-state behavior, but the output schema plus annotations cover the rest.

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, no waste, with the scoping constraint and the active-team marker front-loaded before the routing hint to set_current_team.

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 with an output schema and readOnly annotations, the description is nearly sufficient: scope and active-team flagging are stated, and safety is covered elsewhere. Only edge cases (no teams, non-owner membership) are unaddressed.

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

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

The tool takes zero parameters, so there is nothing for the description to compensate for; baseline 4 applies. The membership and active-team framing is scope information, not parameter documentation.

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

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

States a specific verb and resource (list teams) and adds real scope: only teams where the user is owner or admin, with the active team marked. This decisively separates it from sibling list tools like list_connected_accounts or list_drafts.

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 to set_current_team for switching teams, naming the alternative and the condition. It does not state when *not* to call this tool or what to do when the list is empty, 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?

With annotations already declaring destructiveHint=true, idempotentHint=false, and readOnlyHint=false, the bar is lower. The description adds useful context beyond those hints: removal changes a publicly visible page immediately, which is an important real-world consequence. It does not detail reversibility, permission requirements, or failure behavior, so it is strong but not exhaustive.

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

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

Three short sentences, front-loaded with the action and required identifier. Every sentence earns its place: purpose, prerequisite, and important side effect. No redundant restatement of the tool name or annotations.

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

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

The tool is simple, has an output schema, and annotations already cover the destructive/idempotent profile. The description adds the key operational context (public visibility, immediate effect, get_mini_site prerequisite). It is nearly complete, though the unexplained siteId parameter leaves a small gap for a multi-parameter tool.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the required blockId parameter with examples ('a finished tour date or a retired product link') and says how to find the id via get_mini_site. However, the optional siteId parameter is never mentioned or explained, leaving half of the parameter set undocumented.

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 ('Remove'), resource ('one block from a bio page'), and selector ('by its blockId'). It clearly distinguishes the tool from sibling operations like add_mini_site_block, update_mini_site_block, and get_mini_site, so an agent can route correctly without opening 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?

It gives a concrete prerequisite: 'Call get_mini_site first to find the id.' That tells the agent how to obtain the required blockId. However, it does not explicitly state when to choose this tool over update_mini_site_block or delete_draft, nor does it name exclusions, so it falls short of a full when/when-not routing guide.

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 the basic safety quadrant; the description adds substantial behavioral context beyond them: quota pre-charging to defeat a TOCTOU race, automatic refund conditions (no PUT in 10 min, undersized upload, magic-byte failure), the 50MB hard cap, and that the PUT handler creates the Asset doc and validates magic bytes. This is exactly the kind of non-obvious behavior an agent needs.

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

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

Front-loads the recommendation and the two-step workflow before the caveats, and every sentence carries operational content. It is long, but the length is justified by genuine complexity; there is minor redundancy in the repeated warnings about not retrying, keeping it below a 5.

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

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

Covers the full call lifecycle — request, out-of-band PUT, inline asset-URL return usable in create_post_draft/update_post_draft — plus failure modes, fallback, and quota accounting. An output schema exists, yet the description still tells the agent what the PUT response yields, so nothing needed to invoke 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 0%, so the description must carry the load, and it largely does: it names all three params ({filename, contentType, sizeBytes}), enumerates the allowed content types matching the enum, and states the 50MB cap and size-based quota pre-charge for sizeBytes. Only filename's semantics are left thin, so it falls just short of fully compensating.

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 ('request' an 'asset upload URL' as the 'Recommended upload tool for images and videos') and explicitly distinguishes itself from the sibling `upload_asset` tool. An agent can tell exactly what this does and when it beats the alternative without opening either schema.

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

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

Gives explicit when-to-use ('images and videos of any size', 'anything larger than ~8KB'), when-not ('do not call this tool again expecting a different uploadUrl'), and names the alternative (`upload_asset`). It also documents the egress-restricted fallback path with the manual-upload workaround, so nothing is left 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 declare the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description only needs to add operational context. It does so by stating the draft-existence precondition and the default behavior when scoping params are omitted ('all providers in the PostGroup are queued'), which is genuinely useful beyond the annotations.

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

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

Front-loads the core action in the first sentence and keeps the prerequisite adjacent to it. The scoping sentence is dense but each clause carries distinct information, so little 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?

With an output schema present, return values need no explanation, and annotations carry the safety profile. The description covers the precondition, scoping semantics, and default; only edge cases (e.g. past timestamps, cancellation path) are left unaddressed, which is acceptable for a 5-parameter tool.

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

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

Schema description coverage is 100%, so all five parameters are already documented. The description adds a concrete multi-account scoping example, but its statements about platform/channelName and the omitted-default largely restate the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Move a draft post into the publish queue at a future time'), and the prerequisite ('use create_post_draft first') cleanly separates it from the draft-creation and draft-editing siblings. An agent can identify the action and its scope 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?

Explicitly names the prerequisite tool (create_post_draft) and describes the conditional routing of the optional scoping parameters with a concrete example. It does not spell out when NOT to use it (e.g. immediate publishing, or the cancel_scheduled_post counterpart), so it stops short of a full when/when-not/alternatives treatment.

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 this a safe read (readOnlyHint=true, openWorldHint=false), and the description is consistent with that. It adds a genuinely useful behavioral detail beyond annotations — matching is case-insensitive substring, not fuzzy/token search — but says nothing about result ordering, pagination, or false-positive behavior, which matter most for a search tool.

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 what is searched before the filter details. Slight redundancy in repeating 'case-insensitive' already present in the schema's query description.

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

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

An output schema exists so return values need no explanation, and the annotations cover safety. What is missing is search-behavior completeness: ordering/relevance of results, whether the scope spans teams, and limit semantics for a tool with four parameters.

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 only 25%, so the description must carry weight; it partially does by naming the status and platform filters. However, it never explains limit (default 20, max 100) or the minimum query length, and adds no meaning beyond the enum names already visible in the schema.

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

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

States a specific verb and resource (text-search across posts) and names the scope of records searched (drafts, scheduled, published). It implicitly separates itself from list_drafts and list_scheduled_posts by being content-based rather than enumeration-based, though it never names those 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?

The mention of optional status/platform filters implies when the tool is useful, but there is no explicit 'use this instead of list_drafts/get_post when...' routing. An agent must infer from the sibling list which tool fits a given intent.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new context: the cost model ('Free for all plans (discovery surface)') and what the result set contains, which goes beyond the annotation surface.

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 purpose then usage then return shape. Efficient, though the return-value sentence partly duplicates what the output schema already provides.

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

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

With an output schema present, the return values needn't be explained, so the description focusing on purpose and usage is reasonable. It is nearly complete, with the only real gap being query-vs-intent disambiguation.

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 0%, so the description carries the burden. It names the three filter dimensions ('free-text query, category, or intent') mapping to the three params, but does not explain the distinction between 'query' and 'intent' or give format guidance, leaving a key ambiguity unresolved.

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 ('search and filter') and resource ('the available MCP tool catalog'), and is clearly distinguishable from siblings like search_posts or list_drafts. An agent can tell what this tool does without opening the schema.

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

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

Gives clear context: 'Useful when you have many tools available and want to narrow to the ones relevant to the user's current task without scanning every description.' It establishes when to reach for this tool, though it names no explicit when-not condition or alternative discovery mechanism.

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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description goes well beyond them by disclosing that the switch takes effect immediately for subsequent tool calls and persists across sessions only under OAuth, not API key auth. That is exactly the kind of session-state behavior an agent cannot infer from structured fields.

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 with the action, precondition, and effect ordered front-to-back. Nothing is padded and no clause is redundant with the title.

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

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

An output schema exists, so return values need no explanation, and the description covers the remaining gaps for a state-mutating tool: who may call it, how long the effect lasts, and how authentication mode changes persistence.

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 teamId property already documents both the source (list_teams) and the membership requirement. The description repeats the membership constraint rather than adding format or sourcing 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 — 'Switch the active team' — with the exact scope of the change (this Bearer token). No sibling in the list performs a comparable mutation, so an agent can identify it unambiguously from the name plus this sentence.

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 supplies a real precondition (the user must be a member of the target team) and explains the session/OAuth persistence condition, but never states when to reach for this tool versus alternatives such as list_teams or get_account_health. Usage is implied rather than instructed.

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

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

Annotations declare readOnlyHint=false with idempotentHint=true, and the description explains why a 'test' is a write: it updates the integration's health status. It also discloses what is returned (reachability, token validity, plugin version, capabilities). It does not mention permissions or rate limiting, but adds real value beyond the annotations.

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

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

Three tight sentences, each earning its place: purpose first, then return payload, then parameter/precondition guidance. 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?

An output schema exists, so return values need not be spelled out, yet the description still summarizes them helpfully. For a one-parameter tool with preconditions and side effects covered, it is nearly complete; only error/auth behavior is left implicit.

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

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

Schema description coverage is 0%, so the description must carry the meaning of integrationId. It does so by explaining when it is needed (multiple blogs connected) versus when it can be omitted, which is more than the bare string type in the schema. It still doesn't say where to obtain the ID, keeping it from a 5.

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

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

States a specific verb (test) and resource (connectivity to the team's connected WordPress blog via the PostNext plugin), plus the secondary effect of updating integration health. This clearly separates it from siblings like get_account_health or get_publish_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?

Gives the selection condition for the optional parameter ('Pass integrationId when more than one blog is connected; otherwise the single connected blog is used') and states the precondition that a blog must be connected first. It stops short of naming an alternative tool for troubleshooting, so it is not a full when/when-not treatment.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is well covered. The description adds useful context beyond that: it describes a patch (partial update) and states that only the active profile is mutated, with selection/creation handled outside this tool. It doesn't disclose auth, rate limits, or return behavior, so it's 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?

Three sentences, front-loaded with purpose, followed by usage context and a scoping constraint. No filler or repetition; every sentence earns its place.

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

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

Given the output schema exists, return values need not be described. The description covers purpose, usage, and the key scope limitation. It could be more complete by clarifying that omitted fields remain untouched or by explaining the audienceSize object format, but it is otherwise sufficient for this complexity level.

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

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

Schema description coverage is 0%, so the description must compensate. It names every updatable field conceptually (voice, themes, expertise areas, personality traits, hashtag set, audience-size estimates, bio), mapping to all seven schema properties. It does not explain the nested structure of audienceSize or field constraints, but the schema itself provides types and limits.

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

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

The description uses a specific verb ('Patch') and resource ('user's active brand profile'), then enumerates every updatable field. It also distinguishes this operation from profile selection and creation, which must happen elsewhere. An agent can immediately tell what this tool does.

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

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

It explicitly states when to use it ('when the user wants Claude to refine their brand voice based on a transcript, style guide, or competitor analysis') and when not to use it ('profile selection / creation must happen in the web app'). No alternative sibling tools exist for this resource, and the boundary is clear.

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

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

Annotations already cover safety hints, and the description adds substantial behavior: only passed fields change, block type is immutable, the response returns the block AS STORED with updated/ignored lists that must be checked, and phase:'always' clears staging with no other removal path. This is rich, non-contradictory operational context.

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

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

The description is front-loaded with the core action, then constraints, then response handling and the special phase case. Every sentence adds practical value, though it could be slightly tightened given the volume of detail.

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

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

For a 35-parameter mutation tool with an output schema, the description covers key behavioral semantics (partial update, immutability, response handling, staging removal) but leaves most input parameters unexplained. An agent can understand the tool's nature and safety profile but still lacks guidance on many 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 0% for 35 parameters, so the description must compensate but only gives a handful of examples (link title/URL, price, event date, opening hours, display order) and explains phase:'always'. It leaves most parameters (e.g., days, mode, limit, links, images, faqItems, startDate, etc.) without added meaning beyond their bare schema names.

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 (patch) and resource (one existing block on a bio page), with examples of what can change. It explicitly distinguishes from siblings add_mini_site_block and remove_mini_site_block by noting the block type cannot be changed and that removal/creation is the alternative.

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 clear when-to-use context and alternatives: use for partial updates to an existing block, not for changing block type (remove and add instead), and use get_mini_site first to get blockId. It also explains the special phase:'always' use case for un-staging.

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

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

Beyond the annotations, the description discloses important behaviors: media replaces the draft's media, threadParts replaces thread posts, content only works on single-post drafts, and omitting platform/channelName overwrites all providers uniformly. It also documents alt-text limits and platform-specific caveats, which go well beyond the annotation hints.

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 the core validation rule, then proceeds through parameter-specific guidance in a logical order. It is dense and paragraph-form rather than structured, but nearly every sentence adds actionable detail for this complex mutation tool.

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

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

Annotations already cover safety properties, and an output schema exists, so return values need not be explained — yet the description still mentions dashboardUrl as a bonus. The main gap is the undocumented clientRequestId, which matters for an idempotent update tool, but the rest of the behavioral contract is well covered.

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

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

With 0% schema description coverage, the description carries the burden and explains most semantic parameters: content vs threadParts, media vs mediaUrls, platform scoping, channelName narrowing, and the alt/type fields on media. It leaves clientRequestId entirely unexplained and does not clarify postId or mediaUrls in detail, so compensation is strong but not complete.

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+resource: 'Update an existing draft post.' It clearly distinguishes updating a draft from creating, deleting, or reading one, so an agent can select it without ambiguity against siblings like create_post_draft or delete_draft.

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 at-least-one-field requirement and gives detailed conditions for when to use platform or channelName to scope the update, including what happens when both are omitted. It stops short of naming alternative tools such as create_post_draft or schedule_post, so usage is clear but not fully comparative.

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

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

Beyond the annotations (write, non-destructive, non-idempotent), the description discloses the silent-truncation failure mode, the gap between the server-side 5MB cap and the effective client-side cap, allowed MIME types, and plan storage limits. These are non-obvious behavioral traits the annotations cannot convey.

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

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

Front-loads the decisive 'don't use this by default' warning and uses clear caps-styled emphasis. It is somewhat long and repeats the size-cap idea in three places ('~8KB or less', '~10-15KB chars', 'server cap'), but each block carries actionable content rather than 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?

An output schema exists, so return values need no elaboration, and the description still covers caps, allowed types, plan limits, the preferred alternative, and a network-failure fallback. For a three-param write tool, an agent has everything needed to decide whether 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 coverage is 0% and none of the three parameters carries a description, so the description must compensate. It partially does: it states the 5MB cap (relevant to base64), lists allowed types (matching the contentType enum), and implies the filename role. However it never clarifies the base64 format (raw vs. data-URI prefix) or filename constraints, leaving a real gap for a required param.

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: 'uploads an image or video to your PostNext asset library via base64 and returns a URL for create_post_draft.mediaUrls.' It explicitly distinguishes itself from the sibling tool request_asset_upload, so an agent can tell the two apart without opening either schema.

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

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

Gives explicit when/when-not rules (use only for very small files ~8KB or less; use request_asset_upload for anything larger) and a documented last-resort fallback for environments where neither upload tool can transfer bytes. Alternatives and selection conditions are fully spelled out.

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