Socializioz AI Social Media Agent MCP

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

Annotations already mark destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds valuable context about the opaque nature of post IDs and the strict instruction to never display them, going beyond what annotations provide. No contradiction with annotations.

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

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

The description is two sentences: the first is action-first and states the core purpose, the second adds a critical security constraint. There is no filler or redundant elaboration.

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

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

Given a single parameter, an output schema, and clear annotations, the description covers the essential context: what is canceled, how to identify the post, and a vital privacy rule. It does not discuss edge cases like attempting to cancel an already-canceled post, but that level of detail is not necessary for this simple 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 already provides 100% coverage for postId, including its meaning as an opaque postReference or trusted internal ID. The description repeats this information and adds the additional caveat about never displaying it, but does not substantially exceed the schema's description. Baseline 3 is appropriate.

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

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

The description uses the specific verb 'Cancel' with the resource 'scheduled publication of a post', clearly indicating the operation. It distinguishes from siblings like schedule_post and reschedule_post by explicitly targeting cancellation.

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 cancel a previously scheduled post. It also specifies valid sources for the postId (list_posts/get_post/list_scheduled_posts) and warns against displaying IDs to the user. However, it does not explicitly contrast with alternatives like reschedule_post.

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 by disclosing important behavioral traits: never displaying internal IDs to users, using returned postReference only for follow-up calls, account resolution behavior in Base44 mode, and the need to ask users to choose among matches using friendly labels. These are non-obvious behaviors that an agent must know to use the tool correctly.

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

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

The description is front-loaded with the primary purpose and each subsequent sentence adds critical user-handling or account-resolution guidance. It is somewhat dense, but every sentence earns its place. The structure flows from purpose to restrictions to mode-specific behavior to ambiguity handling, making it 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?

For a tool with 12 parameters, an output schema, and multiple sibling tools, the description covers the essential scenarios: when to create a draft, how to handle IDs, Base44 mode resolution, and account disambiguation. The only minor gap is the undefined 'Base44 mode' term, which might confuse agents without additional context, but overall the description is sufficient for effective selection and 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?

The input schema already covers all 12 parameters with descriptions (100% coverage), so this dimension is at baseline 3. The description adds extra meaning for socialAccountId (omit in Base44 mode unless trusted flow, never display) and accountLabel (use friendly labels only). This justifies one point above baseline.

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

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

The description clearly states the tool's purpose: 'Save a Socializioz draft post when the user explicitly wants a stored draft.' The verb 'save' and resource 'draft post' are specific, and the phrase 'when the user explicitly wants a stored draft' distinguishes it from scheduling or updating tools like schedule_post and update_draft_post.

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

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

The description provides clear context for when to use the tool: 'when the user explicitly wants a stored draft.' It also includes behavioral guidance for ambiguity resolution ('If multiple accounts match, ask the user to choose using friendly labels') and mode-specific instructions ('In Base44 mode, omit socialAccountId unless supplied by an internal trusted flow'). It does not explicitly name alternative tools, but the condition 'stored draft' implies non-use for scheduling/publishing.

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 safety profile is covered. The description adds useful behavioral context, such as the active workspace default and optional workspaceId override, which is beyond the annotations.

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

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

The description is a single, front-loaded sentence that clearly states the action, resource, and content fields. Every word contributes value with no filler 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 is simple with one optional parameter, an output schema, and complete annotations. The description adequately covers purpose, scope, and content, and the output schema handles return value details, so 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 100% and the parameter description already explains the optional workspaceId and default behavior. The tool description only echoes 'active workspace' without adding new parameter details, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns the brand profile for the active workspace, specifying the resource and scope. It distinguishes itself from sibling tools like get_user_profile and get_workspace_context by focusing on brand-specific data.

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 brand profile information and mentions the active workspace context. It does not explicitly name alternatives or when-not-to-use, but the sibling tools are clearly distinct, making the usage context unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the important privacy behavior of never displaying IDs to users, and clarifies the accepted ID origins, enhancing transparency beyond annotations without 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?

Two crisp, front-loaded sentences: the first communicates the purpose and ID sources, the second delivers a crucial privacy warning. No unnecessary detail or repetition, 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?

Given a single parameter, a detailed output schema, and annotations that cover safety, the description is sufficient. It addresses the key usage scenario (following up from list_posts/create_draft_post) and the critical display prohibition, making the tool fully understandable.

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 description already fully covers the postId parameter at 100% coverage, including its opaque nature and usage. The tool description mostly reiterates this, but adds specific references to list_posts/create_draft_post, which slightly enriches the context. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Read') and resource ('a specific Socializioz post'), and clearly distinguishes from siblings like list_posts by focusing on a single post. It also specifies the ID types (postReference or internal post ID), leaving 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?

It explicitly instructs to use an opaque postReference from list_posts/create_draft_post or a trusted internal post ID, and provides a critical usage caution ('Never display...'). Though it doesn't name alternative tools for exclusion, the context is clear for when this tool should be invoked.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about the authenticated user and return contents, but no additional behavioral details like rate limits or prerequisites. This is consistent with annotations and provides some added value over them.

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

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

Two concise sentences: first enumerates return contents, second gives usage guidance. Every word earns its place; no redundancy or filler.

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

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

With 0 parameters and an existing output schema, the description is complete. It communicates the tool's purpose, who it applies to (authenticated user), and positioning relative to other tools. No further detail is needed.

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 schema coverage is trivially 100%. The description correctly avoids fabricating parameter details. With no parameters to describe, a baseline of 4 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?

Description explicitly states 'Return the authenticated user's profile' and enumerates specific contents (default workspace, subscription, brand summary, capabilities). This clearly distinguishes it from sibling tools like get_brand_profile (brand-specific) and get_workspace_context (workspace-specific).

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

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

Provides explicit 'when to use': 'Call this first to discover who is logged in before using other tools.' However, it does not mention when not to use or name specific alternatives, 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, idempotentHint, and destructiveHint=false. The description adds useful context by stating the result is scoped to the authenticated user and includes setup gaps, which goes beyond the generic annotation hints. No contradiction 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?

A single sentence that front-loads the verb and resource, with no redundant phrases. It efficiently communicates the tool's purpose.

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 optional parameter, no required parameters), has an output schema, and strong annotations. The description names the output categories and authentication scope, making it complete for an agent to select and invoke 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 100% for the single optional parameter, including its behavior when omitted. The description adds no parameter-specific detail, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Return') and identifies clear resources: active workspace, subscription, post counts, and setup gaps for the authenticated user. This clearly distinguishes it from sibling tools like get_user_profile or list_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 implies when to use the tool—when workspace context is needed—and the listed contents clarify its scope. However, it does not explicitly state exclusions or alternatives, so it lacks the specificity for 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?

While annotations already declare read-only and non-destructive behavior, the description adds a critical behavioral constraint: 'Never display socialAccountId, accountReference, raw account IDs, or workspace IDs to the user' and requires friendly labels. This goes beyond the structured annotations and is valuable for safe usage.

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 primary purpose and followed by a concise, important usage rule. Every word earns its place; there is no redundancy or ambiguity.

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

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

Given the tool's simplicity (one optional parameter), rich annotations (readOnly, idempotent), and presence of an output schema, the description covers the core purpose and adds a non-obvious display constraint. No significant contextual gaps remain for an agent to select and 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?

The input schema provides 100% coverage with a clear description for workspaceId ('Optional Socializioz workspace ID. Omit to use the user's default workspace'). The tool description does not add further parameter-level meaning, so it relies on the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'List social media accounts connected to a Socializioz workspace' with a specific verb and resource, and is distinct from sibling tools like list_posts or get_workspace_context. It unambiguously identifies the tool's 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?

No guidance is provided about when to use this tool versus alternatives. The description merely states what it does; there are no explicit usage scenarios, exclusions, or references to sibling tools. Usage must be inferred from the function name and description.

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

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

Annotations already declare readOnlyHint true, idempotentHint true, and destructiveHint false, so the safety profile is covered. The description adds valuable behavioral context by instructing never to display IDs and to use postReference only for follow-up calls, which is not inferable from 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: the first conveys purpose and filters, the second adds usage context and a critical constraint. No fluff, front-loaded, every sentence earns its place.

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

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

With an output schema present, return values are documented elsewhere. The description covers the operation's scope, filtering options, and a critical output-handling rule, making it complete for a list tool of this complexity. No significant gaps remain.

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

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

Schema description coverage is 0%, requiring the description to compensate for parameter understanding. The description maps the main filtering concepts (status, channel, date range, account, campaign) to the schema parameters, which is helpful. It omits limit and workspaceId, but those have defaults or are less central to the tool's purpose.

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 'Read Socializioz posts by status, channel, date range, account, or campaign', which clearly specifies the action (read), resource (posts), and key filter dimensions. It also frames the tool's role for pre-edit/scheduling workflows, distinguishing it from single-post or mutation tools.

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

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

The description says 'Use this to show drafts, pending posts, scheduled posts, published posts, failed posts, or all posts before editing/scheduling', giving a concrete use case. It does not explicitly compare with alternatives like get_post, but the context is clear enough for an agent to select this tool when listing is needed.

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

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

Annotations already flag this as destructive and not read-only. The description adds behavioral context beyond this: it specifies that postId can be an opaque postReference from specific prior tools (list_posts/get_post/list_scheduled_posts) or a trusted internal ID, and it imposes a strict privacy rule ('Never display post IDs or postReference values to the user'). This helps the agent understand safe input handling, though it does not detail side effects like overwriting the old schedule.

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 long: the first states the action and input source, the second warns about displaying IDs. It is front-loaded with the primary purpose and contains no redundant or filler text.

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

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

This is a relatively simple tool with only two parameters, both fully described in the schema. The description covers the purpose, input sourcing, and an important privacy constraint. An output schema exists, so return values are handled separately. Overall, the description provides all necessary context for an agent to use this tool correctly.

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

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

The schema description coverage is 100% and explains both parameters well. The tool description adds meaningful cross-references by naming exactly which prior tools return the postReference, which is not in the schema. This extra detail helps the agent know where to obtain a valid postId, going beyond the schema's generic 'prior tool result' phrasing.

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: 'Change the scheduled publish time for an existing scheduled post.' It specifies the resource (existing scheduled post) and the action (change the time), distinguishing it from siblings like schedule_post (which creates new schedules) and cancel_scheduled_post (which removes them).

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: it is for existing scheduled posts and requires an opaque postReference or internal post ID. It does not explicitly mention alternatives or when not to use it, but the context makes it obvious that it is not for creating or cancelling posts. The 'Never display' instruction also provides guidance on handling IDs, though not on tool selection.

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

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

The description adds behavioral context beyond annotations: it warns against displaying opaque post IDs/references to users, and specifies the source of valid identifiers. Annotations indicate it's a non-read, non-destructive action, which aligns with the description. 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?

Two sentences, front-loaded with the primary action, and the second sentence adds a critical security caution. No filler.

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

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

The tool has an output schema and clear annotations. The description covers the purpose, identifier sources, and a security caveat. It doesn't address edge cases like invalid timestamps, but with the schema and sibling tools, it's sufficiently complete for an agent to use correctly.

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

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

The schema already documents both parameters (100% coverage). The tool description adds value by naming the specific tools that return a valid postReference and reiterating the sensitive nature of the ID, reinforcing the schema without redundancy.

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 with a specific verb ('Schedule'), a resource ('existing Socializioz post'), and the outcome ('future publication'). It also specifies accepted identifier types, distinguishing it from sibling scheduling tools like cancel_scheduled_post and reschedule_post.

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

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

It provides clear context on when to use this tool: after obtaining a postReference from create_draft_post/list_posts/get_post, and for existing posts. It does not explicitly exclude alternatives (e.g., reschedule_post for changing times), but the context is sufficient.

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 a non-read, non-destructive operation. The description adds behavior about handling opaque references and the strict rule never to display post IDs or postReference values to users, which is valuable context. It does not detail side effects on the post status, but the annotations cover safety.

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: the first states purpose and input source, the second gives a critical user-facing caution. Every word earns its place, and the key action is front-loaded.

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

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

For a single-parameter tool with an output schema and high schema coverage, the description is sufficiently complete. It informs the agent of the workflow and input handling, though it could mention preconditions like the post being in draft status explicitly. Overall, no major gaps.

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

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

The schema already provides a thorough description of the postId parameter, including its opaque nature and display restrictions. The tool description essentially repeats this information, so it adds no significant semantic value beyond the schema. Baseline 3 is appropriate due to high schema coverage.

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

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

The description clearly states the tool's function: sending a draft post into an approval workflow. It specifies the source of the identifier (opaque postReference from prior tools or trusted internal ID) and distinguishes it from sibling tools like schedule_post or update_draft_post by focusing on the approval workflow.

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

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

The description provides clear context for usage: it instructs to use the opaque postReference returned by specific prior tools or a trusted internal post ID. However, it does not explicitly state when NOT to use this tool (e.g., for direct scheduling) or mention alternatives, leaving some inference to the 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?

Annotations indicate this is a non-read-only, non-destructive operation. The description adds a key behavioral rule: never display post IDs or postReference values to the user. It also clarifies the semantics of the identifier (opaque vs trusted internal ID). 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, front-loaded with the action, and the warning is relevant. No wasted words.

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

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

The description explains the prerequisite (must have a postReference or trusted ID) and the display constraint. With an output schema and annotations present, it is adequately complete for a simple update operation. It lacks explicit mention of partial updates, but the schema makes that inferable.

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 low (25%), with only postId documented. The description repeats the postId semantics already present in the schema but adds no details about title, content, or hashtags. Thus it does not meaningfully compensate for the coverage gap.

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

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

The description clearly identifies the action ('Update'), the target resource ('existing draft post'), and the identifier format (opaque postReference or trusted internal post ID). It distinguishes this from siblings like create_draft_post or schedule_post.

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

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

It provides explicit guidance on where to obtain the postReference (create_draft_post/list_posts/get_post) and warns against displaying IDs. However, it does not explicitly state when not to use this tool or list alternatives, leaving some inference to the agent.

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