postnext

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

Annotations indicate idempotentHint=true and readOnlyHint=false, but the description adds substantial behavioral detail beyond annotations: the idempotent behavior (returning existing block on duplicate), the response returning the block AS STORED (so rejected fields are absent), and the phase field's dependency on campaign being set. This is exactly the kind of contextual behavior an agent needs to know and is not present in the structured metadata.

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

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

The description is dense but well-structured: starts with the core purpose, then enumerates types, followed by required fields, then key behavioral notes. Each sentence carries information, and the structure front-loads the most critical aspects. It's appropriately detailed for a tool with 35 parameters and 18 types, though it could be slightly more scannable with bullet points, but it's not overly verbose.

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 complex tool with 35 parameters, nested objects, and an output schema, the description covers all critical aspects: types, required fields, URL validation, idempotency, phase semantics, and the campaign prerequisite. It even instructs the agent to check get_mini_site.campaign and inform the user if it's null. The output schema likely documents the return structure, so the description doesn't need to repeat that. It is complete for safe and correct invocation.

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

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

Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It does so extensively: lists required fields per type, explains the phase enum, URL constraints, and the meaning of various fields like mode, links, etc. While not every one of the 35 parameters is individually explained, the description covers the most important ones and gives clear rules for required fields. It significantly compensates for the lack of schema descriptions.

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

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

Clearly states 'Add one block to a bio page' with a specific verb and resource. Lists all 18 block types, distinguishing from siblings like remove_mini_site_block and update_mini_site_block by its add semantics. The description is unambiguous about what the tool does.

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

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

Provides explicit per-type required fields, which is essential usage guidance. It also includes important behavioral notes like idempotency (calling twice returns existing block) and the phase field dependency on campaign. However, it doesn't explicitly contrast with update_mini_site_block or remove_mini_site_block, but the purpose is clear enough that an agent can infer when to add vs. update/remove.

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; the description adds context that cancellation affects only the publish queue and preserves the draft. This goes beyond the annotations by clarifying what state change occurs and what doesn't get destroyed.

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 deliver the essential information up front: the operation, its effect on the queue, the preservation of the draft, and idempotency. No unnecessary words or repetition.

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

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

For a simple tool with one required parameter, the description is complete: it states the action, the side effect, and a key behavioral guarantee. The presence of an output schema means return-value details don't need to be spelled out in the description.

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

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

With schema description coverage at 0%, the description partially compensates by implying that postId refers to the scheduled post to cancel. However, it doesn't explain how to obtain the postId or whether it differs from a draft ID, leaving a gap in parameter guidance.

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 ('Cancel'), resource ('scheduled post'), and outcome ('remove it from the publish queue'). It explicitly distinguishes itself from delete operations by noting 'The draft is preserved (not deleted)', which is relevant given the sibling tool 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?

The description provides clear context: canceling a scheduled post removes it from the queue while preserving the draft, and the idempotency note indicates it is safe to call on already-cancelled posts. It doesn't explicitly name an alternative tool for deletion, but the behavior distinction is clearly implied.

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

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

The description discloses a non-obvious behavior beyond the annotations: this tool does not directly connect the account, it only generates a one-time URL that the user must open and authorize. This meaningfully complements openWorldHint=true and readOnlyHint=false. It stops short of explaining the post-authorization state, but the key behavioral trait is present.

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

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

Two short sentences with zero filler. The first sentence states the deliverable (one-time authorization URL) and the second states the required user action, making the tool's flow immediately understandable.

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

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

For a one-parameter tool with an output schema, the description captures the essential flow: generate a URL, user authorizes in a browser. It does not mention what happens after authorization or how to use the URL, but the simple scope and available schema make this adequate.

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

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

The schema has one parameter, platform, with a fully enumerated list of social platforms, so the schema itself carries most of the meaning. The description adds the 'social channel' framing but does not explicitly explain how platform maps to an OAuth provider. With 0% schema description coverage, the description only partially compensates for the missing parameter-level detail.

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 ('Generate') and a concrete resource ('a one-time authorization URL for connecting a social channel'), going well beyond the title. It clearly differentiates this tool from sibling tools like list_connected_accounts, which inspect existing connections rather than initiate one.

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 establishes the essential usage context: the tool produces a URL requiring a separate user-initiated browser authorization step. It does not explicitly name alternatives or state when not to use it, but the interactive flow is clear enough to guide an agent.

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

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

The description goes well beyond annotations to disclose key behaviors: topics generate asynchronously and the plan returns immediately in 'generating' status, requiring polling via list_blog_plans. It also reveals the auto-publish behavior for Business/Teams and how to avoid it with autoPublish:false. Annotations are largely neutral (readOnlyHint false, etc.), so the description carries the full burden, and it does so thoroughly.

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

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

The description is dense and informative but not overly verbose. It front-loads the core purpose, then async behavior, then pricing/feature context, then parameter guidance, and the auto-publish warning. Every sentence earns its place, though it could be slightly tightened. The structure is logical and scannable.

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

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

The description is remarkably complete for a tool with 8 parameters and complex behavior. It explains the async response and polling, the auto-publish side effect and its override, and the parameter defaults. Given that an output schema exists, there is no need to describe return values. The only minor omission is explicit handling of edge cases like required startDate format, but that is covered by the pattern in the schema. For its complexity, this definition leaves little to the agent's imagination.

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 schema description coverage at 0%, the description must explain parameter semantics. It effectively explains the most ambiguous parameters: brandProfileId (selects brand, defaults to team's active profile), integrationId (target blog, defaults to single connected one), and autoPublish (controls auto-publishing). It does not explicitly cover planDays, timezone, startDate, contentLanguage, or competitorDomains, but these are either self-evident or inferable from the tool's purpose. The coverage is strong for the critical parameters.

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

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

The description states a specific action ('Create a blog content plan') and a specific resource (the 'Post Planner' for a brand profile). It clearly distinguishes the tool from siblings like list_blog_plans by explicitly referencing that tool for polling progress, and it implies that create_post_draft or schedule_post are for individual posts rather than full plans. The verb+resource is precise and unambiguous.

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

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

The description gives clear context on when to use this tool: it explains the asynchronous nature and points to list_blog_plans for status checks. It also notes the paid-feature requirement (Basic+) and the auto-publish behavior on Business/Teams, which informs whether to use this tool vs alternatives. However, it does not explicitly state exclusions or compare to direct alternatives like create_post_draft for single posts, so guidance is strong 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 declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, but the description adds context annotations cannot carry: drafts are not auto-published, the idempotency window is 5 minutes, the video-URL format PostNext requires, and the trial-reel follower/non-follower behaviour. This is substantive behavioral disclosure well 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?

Front-loads the core action, then layers conditional guidance in a logical order. The Instagram trial-reel sentence is long but each clause carries a real constraint; still, the paragraph is dense enough that a short bulleted structure would scan faster.

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 7-parameter conditional tool with an output schema, this covers everything an agent needs: required platform/content, account targeting, idempotency, and the conditional media rule. The output schema handles return values, and the description still names dashboardUrl for convenience.

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 does for the non-obvious parameters: channelName vs providerId precedence, clientRequestId semantics, and instagramTrialReel's enum meanings plus the mediaUrls video constraint. It does not cover content length limits or the mediaUrls max of 10, so it is strong but not exhaustive.

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') and immediately scopes it against siblings by noting drafts are not auto-published, which distinguishes it from schedule_post. An agent can tell what this 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 explicit routing conditions: call list_connected_accounts first when multiple channels exist for one platform, pass channelName/providerId to target an account, use clientRequestId for idempotent retries within 5 minutes, and the precise precondition for instagramTrialReel (Instagram + exactly one video). Nothing about when to use it 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 indicate destructiveHint=true, so the description's 'Permanently delete' reinforces this. It adds the refusal behavior for scheduled/published posts, which is beyond the annotation scope and valuable context for the agent. No contradictions with annotations.

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

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

Two sentences, no filler. The primary action is front-loaded, and the exception/alternative is stated succinctly in the second sentence. Every word earns its place.

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

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

The tool has an output schema, so return values are covered elsewhere. The description covers the core action, the refusal condition, and the alternative. For a simple destructive tool with a single parameter, 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 description does not mention the postId parameter at all. The single parameter is self-explanatory by name, but the description provides no additional meaning or constraints beyond the schema's type and minLength. Given the low coverage, the description should compensate but does not.

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

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

The description clearly states the action: 'Permanently delete a draft post.' It specifies the resource (draft post) and the verb (delete). It also distinguishes from sibling cancel_scheduled_post by stating what it refuses to do, making it unambiguous which tool to use.

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

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

Explicitly states when not to use: 'Refuses to delete posts that are scheduled or published' and provides the alternative: 'use cancel_scheduled_post for those.' This leaves no ambiguity about which tool to invoke for non-draft posts.

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

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

The annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral context: it states the tool returns specific counts and token expiry info, and explicitly notes 'Requires a paid plan,' which is not in the annotations. It does not mention pagination or rate limits, but given the readOnlyHint and the tool's simple nature, the description adds sufficient behavioral detail beyond the annotations.

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

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

The description is two sentences with no filler. The first sentence front-loads the core purpose and the key metrics, and the second sentence adds the optional filter and the paid-plan requirement. Every word earns its place; it is concise and well-structured.

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

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

The tool is relatively simple with two optional parameters and an output schema (which presumably defines the return structure). The description covers the main purpose and metrics, but it leaves the meaning of 'windowDays' ambiguous and does not clarify whether the post counts are within the selected window or overall. It also doesn't specify the scope of 'draft count' (e.g., all drafts or drafts within a period). Given the output schema exists, the description is adequate but has notable gaps that could lead to misinterpretation.

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 explain the parameters. It explains 'platform' as a filter ('Optionally filter by platform'), but it does not mention 'windowDays' at all. The schema provides enums and a default, but the description does not clarify that windowDays controls the time range for the post counts or other metrics. With two parameters and one unexplained, the description does not fully compensate for the lack of schema descriptions.

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

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

The description clearly states the tool's function: 'Get an account-health summary across all connected social accounts' and enumerates specific metrics (connected-account count, scheduled/published/failed post counts, draft count, tokens expiring). This is distinct from siblings like list_connected_accounts (which only lists accounts) and get_channel_analytics (which focuses on channel-level analytics). The purpose is unambiguous and differentiates well.

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

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

The description implies usage context: for an overall health snapshot across accounts, optionally filtered by platform. However, it does not explicitly mention when to prefer this over alternatives or provide exclusions. For example, there is no note like 'use get_channel_analytics for per-channel details' or 'use list_connected_accounts for just the account list.' The guidance is implicit rather than explicit, so it meets the minimum but lacks clear routing.

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 and openWorldHint annotations, the description discloses real behavioral nuances: Twitter/Instagram return engagement-weighted scores while LinkedIn/Threads/TikTok rank by post frequency only, times use the supplied IANA timezone defaulting to UTC, and a paid plan is required. This meaningfully informs call expectations.

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

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

The description is compact and front-loaded: the main purpose and output shape appear first, followed by platform nuances and practical constraints. Every sentence carries unique information with no filler or repetition.

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

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

Given the output schema covers the return structure and annotations confirm read-only behavior, the description provides the remaining necessary context: ranking metric, platform exceptions, timezone defaulting, and the paid-plan requirement. An agent has everything needed to invoke the tool correctly.

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

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

With 0% schema description coverage, the description compensates by explaining the timezone parameter's format/default and describing platform-specific behavior for the platform enum. The topN parameter is not explicitly explained, but its meaning is inferable from 'ranked' and the schema's integer bounds.

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 gives a precise verb-resource pair: recommend best (dayOfWeek, hour) slots for the user's next post on a platform touch. It specifies the ranking basis, 90-day window, and platform-specific behavior, making the tool's purpose unambiguous and distinct from analytics or scheduling 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 description clearly frames when to use the tool: before a user's next post, for a given platform, with timezone and plan prerequisites. It does not explicitly name alternatives or provide when-not-to-use guidance, but the context is specific enough for an agent to select it correctly.

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, so the description is not required to restate safety. It adds behavior beyond annotations: returns change against preceding period, follower series, and notes that providerId remains valid after handle changes. These are non-obvious behaviors an agent needs to know.

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 information-dense, with no filler. It leads with the core function, then parameter behavior, then usage guidance. Every sentence earns its place, making it detailed yet efficiently structured.

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

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

Given the output schema exists, the description needn't enumerate return values, but it still lists key metrics. With annotations covering safety, all parameters defaulted and scoping explained, and alternatives named, an agent has everything needed to call the tool correctly.

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

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

Schema description coverage is 0%, so the description must fully explain parameters. It does: defines period values and default, explains the optional platform scoping with channelName/providerId, and clarifies providerId's stability. This is significantly more than the schema provides.

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

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

The description clearly states the tool aggregates performance metrics for one or all channels, and explicitly distinguishes it from sibling tools get_post_metrics and get_best_time_to_post. It names the specific metrics returned, making the purpose unambiguous.

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

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

It provides explicit instructions on when to use the tool (e.g., 'how did LinkedIn do this month?'), how to scope by platform, and when to pass channelName vs providerId. It also tells when not to use it by pointing to alternatives, leaving no ambiguity.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond that by disclosing 'no credit cost' and detailing the return shape (blogConnected, integration summary without secrets, latest post title/snippet/publish status/URL). It does not contradict annotations.

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

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

Two sentences deliver purpose, return fields, safety, cost, and usage guidance without redundant wording. The main intent ('Check whether...') is front-loaded, and every clause earns its place.

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

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

For a zero-parameter read-only tool with an output schema, the description fully covers what the tool does, what it returns, when to use it, and its cost/read-only nature. No important information for correct invocation 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 input schema has zero parameters, so schema description coverage is effectively 100% and there is nothing to document. Baseline for 0 parameters is 4; the description appropriately focuses on output and purpose instead.

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: check connection and get the latest post snippet. It explicitly names sibling tools (create_blog_plan, test_blog_connection) and clarifies its distinct role, so an agent can tell it apart 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?

Gives explicit when-to-use guidance: 'Use before create_blog_plan or test_blog_connection to see if a blog is wired up and what was last published.' This names alternatives and the condition that selects this tool over them, leaving no ambiguity.

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

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

Beyond the readOnlyHint=true annotation, the description discloses truncation behavior ('Long text blocks are truncated to a 300-character preview') and hard exclusions ('Never returns email-sync credentials or tracking pixel IDs'). It also states exactly which data is returned in full, giving the agent an accurate coverage model of the call.

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

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

Four sentences, each earning its place: scope enumeration, parameter omission rule, truncation warning, and exclusion list. The purpose is front-loaded in the first phrase, with supporting detail ordered by importance.

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 single optional parameter, a readOnlyHint annotation, and an output schema present, the description completes the picture: full return scope, truncation limit, and exclusions. Nothing an agent needs to invoke the tool correctly or predict its output is missing.

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

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

Schema coverage is 0% and the bare schema exposes a single undocumented optional siteId, so the description must carry the meaning. It adds real value by stating when the parameter can be dropped ('Omit siteId when the team has exactly one site'), implying optionality and multi-site disambiguation. It stops short of explaining how to obtain a siteId via a sibling tool, but the guidance given is substantive.

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 leads with a specific verb+resource pair ('Read one bio page in full') and enumerates the precise return scope: profile header, social icons, every content block type, SEO metadata, theme and auto-pin settings. This scope clearly separates it from siblings like list_mini_sites (a list operation) and get_mini_site_analytics (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 offers one explicit call-time rule: 'Omit siteId when the team has exactly one site.' However, it never names alternatives or states when another tool should be chosen instead—e.g., list_mini_sites for site discovery or get_mini_site_analytics for metrics. The credentials/pixel-ID exclusion is behavioral disclosure, not routing guidance, so choosing between siblings 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?

The description goes well beyond the readOnlyHint/openWorldHint annotations by disclosing a critical data subtlety: all counters are LIFETIME totals except the attribution rows, which use a configurable window. It even instructs the agent to communicate this distinction when reporting, which is high-value behavioral guidance.

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 dense sentences carry substantial information with zero filler. The most important facts—lifetime vs. windowed semantics and the siteId omission rule—are front-loaded and easy for an agent 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?

For a read-only analytics tool with a full output schema, the description covers the tool's scope, metric semantics, parameter behavior, and a notable edge case. Nothing essential to selecting or invoking the tool 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 meaningfully: it explains attributionDays via 'configurable recent window' and clarifies siteId's optionality with the single-site team rule. It could more explicitly define siteId as an identifier of the mini site, but the provided hints are sufficient for correct invocation.

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 unambiguously defines the resource (a bio page / mini site) and enumerates the exact metrics returned: views, clicks, best-performing links, visitor dimensions, crawler reads, and post-to-click attribution. This level of specificity distinguishes it from broader analytics siblings like get_channel_analytics.

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

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

The bio-page framing gives a clear context for when to use this tool, and the note 'Omit siteId when the team has exactly one site' is a concrete usage rule. It does not explicitly name alternatives or when-not-to-use conditions, but the scope is clear enough to route an agent correctly.

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, so the description's burden is lighter. It adds useful scope transparency by naming the returned billing-date fields and clarifying that this tool does not cover quotas and usage. It does not discuss auth expectations or edge cases like an absent plan, but that is minor for a zero-parameter read-only 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 purposeful sentences with no wasted words: output definition, example triggers, and alternative-tool routing. The most important scope information is front-loaded in the first sentence.

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

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

For a zero-parameter, read-only, idempotent tool with an output schema and clear sibling differentiation, the description covers everything an agent needs to invoke it correctly. It states what it returns, when to use it, and when to use get_plan_limits instead.

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

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

The tool has zero parameters and the schema is empty, so there are no parameter semantics to explain. The description still adds value by specifying what the returned data includes, which is sufficient given the absence of parameters.

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

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

The description opens with a specific verb and resource: 'Return the user's plan + billing-date info', then enumerates the exact fields (tier, renewal date, trial end date, cancel-at-period-end state). It clearly distinguishes itself from get_plan_limits by stating this tool is 'purely about plan identity and billing dates'.

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

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

It provides concrete triggering user queries ('when does my plan renew?', 'how many days left on my trial?', 'is my subscription cancelling?') and explicitly excludes quotas/usage requests, routing them to get_plan_limits. This leaves no ambiguity about when to select this tool over siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds the behavioral detail of no AI credit cost and availability on every plan, which is valuable context beyond annotations. It does not contradict annotations. Some additional details (e.g., rate limits or exact response shape) are absent, but the annotations carry the safety profile.

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

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

The description is compact: two sentences, the first states purpose and the second gives usage triggers. Every sentence earns its place, and it is front-loaded with the core purpose. No fluff or redundancy.

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

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

The tool has an output schema (present in context), so return values are already defined. The description covers what the tool returns, when to use it, and its cost characteristics. For a read-only, parameterless tool, this is fully complete – an agent has everything needed to decide when and how to invoke it.

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

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

The tool has 0 parameters, so the description need not explain them. The schema already fully documents the empty parameter set. Baseline for 0 params is 4, and the description doesn't need to compensate. The description correctly avoids inventing parameters.

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

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

The description clearly states the tool returns the user's subscription tier and per-tier quotas (channels, storage, AI credits, posting). The verb 'Return' and resource are specific. It does not explicitly differentiate from the sibling 'get_plan', but the added 'limits/quotas' detail provides some distinction. A clear, unambiguous purpose.

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

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

The description explicitly states when to call it: when the user asks about plan/limits, and proactively before potentially blocked actions, with concrete examples (before create_post_draft when aiCalls is low, before schedule_post on FREE, before connect_channel near cap). It also notes availability on every plan with no AI credit cost. This is exemplary usage guidance with exclusions and alternatives implied.

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 the description adds useful return-value details (content map, status, timestamps, dashboardUrl) that go beyond the annotation. No contradiction exists, and the description provides additional context about what the read operation returns.

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

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

The description is a single, tightly written sentence that front-loads the action and includes the key return fields without any filler. Every clause earns its place.

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

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

With an output schema present and a single parameter, the description covers the essential behavior and return payload. It lacks explicit guidance on when to use it vs. siblings, but that gap is partially mitigated by the clarity of the purpose. Overall, it is sufficiently complete for a read-only single-fetch 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 schema has 0% description coverage, so the description must compensate. It mentions 'by its postId' but does not explain the origin of the ID (e.g., from list operations) or its format. Given only one parameter and a universally understood concept, the minimal mention is adequate but not detailed.

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

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

The description clearly states the verb 'Fetch', the resource 'a single post', and the scope 'draft or scheduled'. It distinguishes itself from sibling list tools (list_drafts, list_scheduled_posts) and metric/status tools (get_post_metrics, get_publish_status) by emphasizing it returns the full content map and metadata.

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

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

The description implies the tool is for retrieving a single post by ID, but does not explicitly state when to prefer it over alternatives like get_post_metrics or list_scheduled_posts. It does clarify it covers both drafts and scheduled posts, which narrows its context, but no explicit exclusions or alternate routing are provided.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral detail: it discloses that engagement is not collected for LinkedIn/Threads/TikTok and that those platforms return publish status+URL instead. This goes beyond annotations and sets accurate expectations about the data completeness. No contradictions.

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

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

The description is two sentences, front-loaded with the action and resource, then adds platform-specific details. Every sentence earns its place; there is no fluff or repetition of schema or annotation information.

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

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

The tool is simple (one parameter, output schema exists), and the description covers the purpose, scope, and platform-specific return behavior. With the output schema providing return structure, nothing critical is missing for an agent to call it correctly. It explains the main nuance (which platforms have metrics) clearly.

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 adds meaning by specifying that the postId must refer to a published post that was sent to platforms, and it explains the outcome for different platforms. However, it does not elaborate on how to obtain the postId, format constraints, or error cases. It provides some semantic value but not enough to fully cover the parameter.

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

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

The description clearly states the verb ('Fetch'), the resource ('engagement metrics for a published post'), and the scope ('across every platform it was sent to'). It distinguishes itself from siblings like get_post (which likely returns general post data) and get_publish_status (which focuses on status) by specifying the metric types and platform coverage. No ambiguity.

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

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

The description provides clear context on when to use the tool: when you need engagement metrics for a specific post across platforms. It also explains platform-specific behavior (Twitter/Instagram return metrics, others return only status+URL), which helps an agent decide if this tool meets its needs. However, it does not explicitly name alternatives or state when not to use it, 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?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral context beyond annotations by specifying the draft edge case (isScheduled=false) and mentioning per-platform error details. This goes beyond what annotations imply, though it does not describe all possible return 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 sentences with zero fluff. The first sentence states the core purpose, and the second provides usage guidance and an edge case. It is front-loaded and every word earns its place.

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

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

For a simple read-only tool with one parameter and an output schema, the description covers the main purpose, usage scenarios, and a notable edge case. It does not explain all output fields, but the output schema handles that. The description is sufficiently complete for an agent to invoke 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?

Schema coverage is 0% because the description does not explicitly describe the postId parameter. However, the context 'for a scheduled post' and the parameter name make its purpose obvious. The description adds minimal value beyond the schema's name and type, but for a single self-explanatory parameter, a 3 is appropriate.

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

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

The description clearly states the tool's purpose: diagnosing a scheduled post's queue/publish state, per-platform success/error, and worker processing time. It distinguishes itself from siblings like get_post (content) and get_post_metrics (metrics) by focusing on publish status, and it includes a specific edge case (isScheduled=false for 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?

The description provides explicit usage scenarios ('did my post go out?' or 'why did Tuesday's post fail on LinkedIn?'), which tells the agent when to invoke this tool. It does not explicitly name alternative tools or list when not to use it, but the scenarios are clear enough for a read-only diagnostic tool.

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

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

Annotations already cover read-only, idempotent, and non-destructive traits. The description adds extra behavioral context: 'no credit cost', ordering (newest first), and the shape of returned data (per-status counts, credit-reservation info, dashboard link). These go 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 sentences, front-loaded with the core purpose, then details and usage. No filler, though it redundantly states 'Read-only' which is already in annotations. Slight redundancy is minor, but it's otherwise efficient.

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

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

For a simple list operation, this is fairly complete: it describes the output content, provides usage scenarios, and the output schema defines the return shape. The only gap is the semantics of the 'limit' parameter, which is a minor omission given the schema's presence.

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 mentions the status filter and repeats its enum values, but it does not explain the 'limit' parameter at all. The limit controls how many plans are returned, which is a meaningful aspect an agent would need to understand.

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

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

The description clearly states the tool lists the team's blog plans (the 'Post Planner'), specifying details like status, per-status counts, credit info, and a dashboard link. It distinguishes itself from sibling tools like create_blog_plan and get_plan by naming the specific resource and operation.

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

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

It provides explicit use cases: to see existing plans before creating a new one or to check generation progress. No explicit exclusions or alternatives are mentioned, but the context is clear enough to guide selection.

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

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

Annotations already declare readOnlyHint=true, but the description adds a valuable behavioral fact: the providerId remains constant when the handle changes. This is a subtle but important trait that an agent must know to avoid misusing the data. The description does not contradict annotations and goes beyond the simple read-only signal by explaining the meaning of the returned identifiers in relation to other tools. This justifies a 4.

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

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

The description is two sentences with zero waste. The first sentence states the core purpose, and the second adds essential behavioral context about the providerId and its use in other tools. It is front-loaded with the action and remains dense without redundancy. This is an exemplary level of conciseness.

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

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

For a zero-parameter, read-only list tool that returns an array of accounts, the description fully covers what an agent needs to call it correctly: it lists the accounts, identifies the key fields, and explains how to use a field downstream. The presence of an output schema means return shape is already handled, so the description does not need to duplicate that. Nothing necessary is missing, so a 5 is justified.

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

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

The tool has no parameters; the schema contains no properties. With the schema coverage at 100%, there is nothing for the description to add about parameters. According to the calibration, a baseline of 4 applies for zero parameters because the schema is complete and the description does not need to explain anything. The description correctly omits parameter details.

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

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

The description states a specific verb (List) and resource (social accounts) and scopes it to the user's team. It also names key attribute concepts (handle, providerId) and distinguishes it from sibling functions like connect_channel and get_account_health by describing what it returns. This is unambiguous and serves as a clear pointer to the tool's function.

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 when to use the tool: to obtain providerId values that are stable identifiers for later use in create_post_draft and get_channel_analytics. It does not explicitly contrast with alternative listing tools, but the context makes the intended use clear. A 4 is appropriate because it provides clear context and downstream usage, though it stops short of explicit exclusions or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral details about the returned entries: deduplicated platform labels, per-provider handles, a content preview from the first provider, and a dashboardUrl. It does not mention ordering or pagination, but given the read-only annotation and simple scope, this is sufficient.

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 main purpose, then explains return fields and ends with a practical filtering instruction. Each sentence earns its place, though the enumeration of fields is somewhat detailed.

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 low-complexity, read-only list operation with an output schema, the description covers the scope, key returned fields, and client-side filtering behavior. 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?

There is only one optional 'limit' parameter, and the schema already defines its type, default, minimum, and maximum, making it self-explanatory. The description does not add any param-level meaning or mention pagination, so it provides no value beyond the structured schema.

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

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

The description states a specific verb ('List') and resource ('the user's draft posts'), and distinguishes drafts from scheduled posts with '(not yet scheduled)'. This makes the tool's purpose unambiguous and separates it from siblings like list_scheduled_posts without needing to inspect 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?

The description gives clear context by specifying that this lists drafts, not scheduled posts, and explicitly instructs client-side filtering by platforms/channelNames when a specific platform or account is desired. It does not explicitly name alternatives or edge cases where another tool should be used, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds behavioral context beyond annotations: it specifies the team scope, the output fields (URL, publish state, setup progress), and the dependency of sibling tools on its siteId. It doesn't mention pagination or limits, but for a simple zero-param list tool, this is adequate and consistent with the read-only hint.

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 with no filler. The purpose and key output fields are front-loaded, and the usage guidance is concise and actionable. Every clause earns its place, making it easy for an agent to parse quickly.

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

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

Given that the tool has zero parameters, an output schema exists (though not shown in the input), and annotations cover read-only safety, the description is complete. It tells the agent when to use it, what it returns, and how it fits into the broader mini-site toolchain. Nothing an agent needs to call it correctly is missing.

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

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

The tool has zero parameters, so per the rubric the baseline is 4. The description provides no parameter-specific details because none exist; there is nothing more to add. The schema coverage is effectively 100% (no properties), and the description's mention of 'currently selected team' clarifies the implicit context, which is valuable.

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 ('List'), resource ('bio pages/mini sites'), scope ('currently selected team'), and the returned fields (public URL, publish state, setup progress). It clearly distinguishes itself from sibling tools by explaining that other mini-site tools consume its returned siteId, which differentiates it from list_teams and other list tools.

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

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

Explicitly instructs to use this tool first when the user mentions 'my bio page', 'link in bio', or 'mini site', and explains the relationship to every other mini-site tool (they take the siteId it returns, and can omit it when there's exactly one site). This provides clear when-to-use and alternative routing with no ambiguity.

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

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

Beyond the read-only annotation, the description reveals concrete query behavior: it joins ScheduledPost with PostGroup, includes content preview and channelName, enforces an upper bound via limit, and orders results by scheduledAt ascending. It also discloses that handle filtering is left to the caller client-side.

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 with no filler. The core definition comes first, followed by join/return details and ordering, all of which earn their place.

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

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

For a read-only list tool with an output schema, the description covers the main behavior, ordering, and limit. The single notable omission is the `from` parameter's semantics, so it is not fully 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 only clarifies `limit` ('Returns up to limit posts'); the `from` datetime parameter is never explained, leaving its filtering semantics ambiguous.

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 the verb 'List' and a specific resource: 'scheduled (queued for publish, not yet sent) posts.' It further distinguishes the tool by describing the join with PostGroup, content preview, and channelName, so an agent can tell this from list_drafts 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?

The description gives clear context: this is for posts queued but not yet sent, and it notes the client-side filtering use case. It does not explicitly name alternatives or state when not to use this tool, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=true, so the read-only nature is already known. The description adds useful context beyond that: teams included are those the user belongs to as owner or admin, and the active team is marked in the output. No contradiction 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?

The description is two compact sentences with no filler. It front-loads the core purpose and then adds the cross-reference to set_current_team, making every word useful.

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

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

For a parameterless read-only list tool with an output schema and supporting annotations, the description covers the essential behavioral details. There is no missing information an agent would need to invoke the tool correctly.

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

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

There are zero parameters, so there is no parameter documentation burden. The description correctly focuses on output behavior instead of parameters, matching the baseline expected for a parameterless tool.

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

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

The description uses a specific verb 'List' with a clear resource 'teams' and scope ('the authenticated user belongs to (as owner or admin)'). It also states that the currently active team is marked, which adds precision beyond the title. It is easily distinguishable from the sibling set_current_team.

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

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

The description clearly indicates this tool is for listing the user's teams and explicitly points to set_current_team for switching. It provides strong contextual guidance, though it does not explicitly state when not to use this tool or list alternative listing tools.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds the meaningful context that the change is publicly visible and immediate, which is beyond the annotation data and helps the agent understand the impact. No contradiction with annotations.

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

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

Two sentences with zero fluff. The core action is front-loaded, followed by a prerequisite and an impact statement. Every sentence earns its place, making it highly scannable.

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 return values are already defined. The description covers purpose, prerequisite, and impact. It is complete for a simple deletion operation, though it could have mentioned the siteId parameter to be fully thorough.

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

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

The description explains blockId well (how to obtain it, examples), but siteId is not mentioned at all. Since schema description coverage is 0%, the description should compensate for both parameters. It partially covers blockId but leaves siteId undefined, which is a gap for an optional parameter.

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

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

The description clearly states the action ('Remove one block'), the resource ('bio page'), and the identifier ('blockId'), with concrete examples (finished tour date, retired product link). It unambiguously distinguishes this from the sibling tools add_mini_site_block and update_mini_site_block.

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

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

Explicitly instructs the agent to call get_mini_site first to find the blockId, providing a clear prerequisite. The examples ('finished tour date', 'retired product link') signal when this tool is appropriate, and the destructive nature is obvious from the verb.

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

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

Annotations only say readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the description carries the burden. It discloses the two-step flow, the PUT handler behavior (creates Asset doc, validates magic bytes, returns inline), the storage quota pre-charge and refund conditions, the 10-minute expiry, the 50MB cap, and the host-reachability failure mode. This is rich behavioral context beyond what annotations provide.

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

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

The description is long but every sentence earns its place: the two-step flow, the alternative tool, the quota/refund behavior, the allowed types, the cap, and the fallback. It is front-loaded with the core flow and the most important usage rule. The fallback paragraph is somewhat verbose but contains critical operational guidance, so the length is justified.

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

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

For a tool with 3 required params, an output schema, and no nested objects, the description is complete. It explains the full lifecycle (request → PUT → asset URL → pass to create_post_draft/update_post_draft), the failure mode, the fallback, and the quota implications. An agent has everything needed to invoke it correctly and handle errors.

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 all three parameters ({filename, contentType, sizeBytes}) and adds meaning: sizeBytes is used for quota pre-charging and has a 50MB cap, contentType is restricted to the allowed types list, and filename is part of the upload request. It doesn't give per-parameter syntax details, but the schema already provides types and enums, and the description adds the behavioral significance of sizeBytes.

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 ('Request an asset upload URL'), the resource (asset upload), and the exact two-step flow. It explicitly distinguishes itself from the sibling `upload_asset` tool by naming it and explaining when to prefer this one, so an agent can tell them apart 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?

The description gives explicit when-to-use guidance ('Always prefer this over the inline `upload_asset` tool for anything larger than ~8KB'), names the alternative, and provides a detailed fallback for sandboxes that can't reach the host. It also warns against retrying and tells the agent exactly what to do instead, which is strong usage guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds valuable behavioral context: the multi-channel behavior (which providers get queued) and the timezone handling for local times. It does not contradict any annotations, and it explains the side-effect of scheduling (moving to publish queue) without hiding anything.

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

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

The description is three sentences with no filler. The core purpose is front-loaded, then the optional narrowing behavior is explained, and finally the default behavior. Every sentence earns its place and the structure is 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?

An output schema exists, so return values are covered. The description covers the main use case, the prerequisite, and optional scoping. It doesn't discuss edge cases like invalid postId or past times, but these are not essential for an agent to invoke the tool correctly. It is complete enough for a scheduling tool.

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

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

Schema coverage is 100%, so the schema already documents every parameter. The description goes beyond by explaining the interaction between platform and channelName with a concrete example ('@bogdanvazzolla X variant') and clarifying the timezone usage for local times. This adds semantic value beyond the schema's individual field descriptions.

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

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

The description opens with a specific verb and resource: 'Move a draft post into the publish queue at a future time.' It clearly states the action and distinguishes itself from siblings like create_post_draft (creates) and cancel_scheduled_post (cancels). The scope is unambiguous.

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

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

It explicitly states the prerequisite: 'The draft must already exist (use create_post_draft first).' It also explains when to use the optional platform and channelName to narrow scheduling, and the default behavior when omitted. It does not explicitly mention alternative tools for scheduling vs. cancellation, but the purpose is clear enough that an agent can infer when to use this tool.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context such as case-insensitive substring matching and that drafts/scheduled/published are all included, but it does not go further into pagination, result ordering, or rate limits.

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

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

Two tight sentences with no filler. The primary behavior and scope are front-loaded, and the optional filters are mentioned without unnecessary detail.

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

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

Given the read-only annotation, an output schema, and a moderate 4-parameter surface, the description covers the core search semantics, scope, and filters. It is complete enough for an agent to invoke correctly, though it could have added a hint about when to prefer list_drafts/list_scheduled_posts for non-search listing needs.

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%, and the description does not compensate enough. It mentions optional status/platform filters but does not explain limit behavior, how filters combine, or the meaning of the status enum values. The query parameter's schema already describes the substring match, so the description adds minimal new parameter-level information.

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+resource ('Text-search across the user's posts') and defines the exact matching behavior ('case-insensitive substring match on post content'). It also scopes the resource to drafts, scheduled, and published posts, which clearly distinguishes it from sibling tools like list_drafts or 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 description establishes clear context: use this tool when you need text-based search across post content, with optional status/platform filtering. It does not explicitly say 'use list_drafts instead when not searching,' but the intended use case is evident.

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 include readOnlyHint=true, so the description doesn't need to repeat that. It adds value by disclosing return content (categories, requiresScope, one-line descriptions, matched tags) and the 'free for all plans' aspect, which are beyond the annotations. No contradiction.

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

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

The description is three sentences with no wasted words. The primary purpose is front-loaded, and each sentence contributes useful information: what it does, when to use it, and what it returns.

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

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

Given the tool's simplicity, the description covers its purpose, usage context, and return values. It doesn't mention pagination or limits, but the output schema likely covers return structure. The 'free for all plans' note adds operational context. Overall, complete for an agent to call correctly.

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

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

Schema coverage is 0%, so the description must compensate. It mentions the three search dimensions (query, category, intent) but doesn't elaborate on allowed values, formats, or interactions between them. It provides basic meaning beyond the schema, but not full compensation for the lack of schema descriptions.

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

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

The description clearly states it searches and filters the MCP tool catalog by query, category, or intent, distinguishing it from sibling tools like search_posts (which searches posts). The verb 'search and filter' with the resource 'tool catalog' is specific and unambiguous.

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

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

It provides a clear when-to-use scenario: when many tools are available and you need to narrow down without scanning all descriptions. It doesn't explicitly name alternatives or say when not to use, but the context is clear enough for an agent to infer.

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 adds meaningful behavioral context: the effect is immediate, session-wide, and persists only under OAuth authentication, not API key. It also states the membership prerequisite. This is exactly the kind of side-effect and auth detail that annotations alone do not 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?

The description is three short, purposeful sentences: purpose, prerequisite, and behavioral effect. Every sentence contributes distinct information, and the most important purpose is front-loaded. There is no fluff or redundant 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?

For a simple one-parameter state-switching tool with full schema coverage and an output schema, the description covers everything an agent needs: what resource is affected, the membership precondition, immediate effect on subsequent calls, and the persistence caveat. No critical behavioral or usage gap remains.

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

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

The single parameter teamId is fully documented in the schema, including the instruction to take it from list_teams and the membership requirement. The description repeats the membership condition but adds no additional parameter-level meaning beyond what the schema already provides. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource — 'Switch the active team for this Bearer token' — and clearly distinguishes this from sibling tools like list_teams or content operations. An agent can immediately understand this is a session-scoped selection action, not a query or content mutation.

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

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

The description gives clear context for when the tool is appropriate: it changes the active team for subsequent tool calls, requires membership, and notes auth-dependent persistence. No alternative sibling performs this role, so explicit when-not-to-use guidance is not necessary, but the membership and session-scoping conditions are clearly 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?

Adds real behavioral context beyond annotations: the tool not only checks connectivity but 'update[s] the integration's health status' — a mutating side effect consistent with readOnlyHint=false and idempotentHint=true. This disclosure is valuable since annotations alone would not reveal the health-status update.

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 core purpose, then returns, then parameter guidance and preconditions. No filler; each sentence adds distinct information. Could be marginally tighter but is appropriately sized.

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?

Complete for a 1-optional-param tool: covers purpose, side effect, param semantics, and prerequisites. Since an output schema exists, the return-value shape is already covered and need not be restated. No material gaps for correct invocation.

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

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

With 0% schema description coverage, the description carries the full burden for integrationId and compensates well: it explains the condition for passing it (multiple connected blogs) and its fallback behavior (single blog used otherwise). Adds meaning the schema's bare string type cannot convey.

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 ('Test connectivity to the team's connected WordPress blog') plus the side-effect of updating health status. Clearly distinguishes from all 32 siblings — none of which are connectivity/diagnostic tools — so an agent can tell this apart 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?

Explains when to pass integrationId ('when more than one blog is connected; otherwise the single connected blog is used') and notes the prerequisite ('a blog must be connected first' / Business/Teams feature). Does not explicitly name excluded alternatives, but the diagnostic purpose and preconditions make usage context 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 convey mutability (readOnlyHint=false), idempotency, and non-destructiveness. The description adds valuable behavioral context by clarifying this is a partial patch, that only the active profile is mutated, and that profile selection/creation is outside this tool. No contradiction with annotations.

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

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

Three short sentences with no filler. The action and resource are front-loaded, the usage context is in the second sentence, and the boundary condition is in the third. 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?

Since an output schema exists, omitting return-value details is acceptable. The description covers what can be patched, when to use it, and the key limitation that profile selection/creation is web-app only, making it self-sufficient for correct invocation.

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

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

With 0% schema description coverage, the description must compensate, and it does by mapping business concepts to schema fields: voice→brandVoice, themes→mainThemes, hashtag set→preferredHashtags, audience-size estimates→audienceSize, plus expertise areas, personality traits, and bio. It does not detail the nested audienceSize structure, but the mapping is sufficient for practical use.

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 ('Patch') and a precise resource ('the user's active brand profile'), then enumerates the affected fields. This clearly distinguishes it from sibling update tools by naming the resource and the active-profile scope.

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

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

The description explicitly frames when to use the tool: when the user wants Claude to refine their brand voice from a transcript, style guide, or competitor analysis 'without leaving the conversation.' It also states a clear exclusion—profile selection/creation must happen in the web app—so the agent knows not to attempt those here.

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 indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description goes beyond these by explaining that only provided fields are changed (partial update), that the block type cannot be changed, and crucially, it describes the response behavior: it returns the block as stored, with 'updated' listing only changed fields and 'ignored' revealing server-rejected fields. It also warns to check 'ignored' before confirming a change, and explains the only way to un-stage a block (phase:'always'). This is rich behavioral context that annotations don't cover.

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

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

The description is a single, dense paragraph that is front-loaded with the primary purpose and partial-update semantics. It covers essential caveats (type change, response 'updated'/'ignored', phase:'always') without excessive fluff. It could be slightly more structured (e.g., bullet points) but remains readable and information-dense.

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 complexity (35 params, nested objects, enums) and the presence of an output schema, the description covers the key operational aspects: partial updates, immutability of block type, response interpretation, and the unique phase behavior. It also directs the user to get_mini_site for the blockId. However, it does not specify which parameters correspond to which block types (e.g., event vs product), but that may be inferable from schema names. The output schema exists, so return structure is covered. Overall, it is almost complete for an agent to call correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the 35 parameters. It does mention the broad categories of fields (link title, URL, price, event date, opening hours, display order) and specifically explains the 'phase' parameter in the context of 'always' clearing staging. However, it does not detail each of the 35 parameters, but given the large schema, the description provides a useful high-level summary and highlights the key parameter ('phase') with non-obvious behavior. This adds value beyond raw 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?

The description clearly states it patches an existing block on a bio page and lists the types of fields that can be changed (link title, URL, price, etc.). It distinguishes from sibling add_mini_site_block and remove_mini_site_block by focusing on patching an existing block, but it does not explicitly name these siblings, so differentiation is implicit rather than explicit.

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

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

The description provides explicit guidance on when to use this tool: it mentions using get_mini_site first to get the blockId, and states that the block type cannot be changed—if that's needed, remove and add a new one instead. It also gives a specific scenario for using phase:'always' to clear staging, which is a clear when-to-use instruction.

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

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

Annotations already mark it as mutating, non-destructive, and idempotent; the description adds valuable behavioral context about scoped updates and the 'overwritten uniformly' consequence. It also discloses the dashboardUrl return value and the required content/mediaUrls condition. No contradiction with annotations.

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

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

Three information-dense sentences, front-loaded with the core action and requirement before scoping details. Examples are brief and directly clarify behavior rather than 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?

For a 6-parameter update with one required field, the description covers the required precondition, optional scoping parameters, default behavior, and return value. Nothing needed to call it correctly is missing.

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

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

With 0% schema description coverage, the description carries the burden and does well: it explains the content/mediaUrls requirement, platform semantics, channelName selection, and default behavior. postId is inferable from the schema, but clientRequestId is left unexplained, so it is not a perfect 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?

Opens with 'Update an existing draft post'—a specific verb and resource—and clearly frames the operation as modifying an already-created draft rather than creating or deleting. The platform/channel scoping details further distinguish it from sibling tools like create_post_draft and 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?

Gives explicit conditions: platform narrows the update to one provider, channelName further narrows it to one account, and omitting both overwrites all providers uniformly. It does not explicitly name sibling tools or state when to prefer create_post_draft, so it stops short of a full when-to-use vs alternatives 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?

Beyond annotations (which show no readOnly/idempotent hints), the description discloses critical behaviors: silent truncation when base64 exceeds context cap, 5MB server-side limit, allowed content types, and failure modes with fallback instructions. This adds substantial context that annotations alone do not provide.

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

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

The description is lengthy but front-loaded with the most critical warning about size limits, followed by usage and fallback. Every section adds necessary context, though it could be tightened. The warning is placed first, which is good for agent attention.

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 usage, limits, allowed types, failure modes, and fallback. The output schema exists and the description mentions the returned URL, so completeness is high. Given the tool's complexity and the importance of the warning, nothing critical is missing.

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

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

Schema coverage is 0%, so the description carries the burden. It mentions the base64 path and size limits, and lists allowed types matching the enum, but does not explicitly describe filename or contentType beyond the purpose. It adds some value but not comprehensive parameter guidance for all three parameters.

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

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

The description clearly states the tool uploads an image or video via base64 to the asset library and returns a URL for use in create_post_draft.mediaUrls. It also distinguishes it from sibling request_asset_upload by explicitly naming the alternative, making the purpose unambiguous.

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

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

Explicitly states when to use this tool vs. the sibling: 'For anything larger, USE request_asset_upload instead' and explains the cap. It also provides a detailed fallback (manual upload) for sandboxed environments, covering both alternative paths and exclusions.

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