Socializioz ChatGPT MCP

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context by specifying the source of postId and warning against displaying IDs, but could further clarify edge cases (e.g., what happens if the post is already published).

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 concise sentences with no wasted words. It is front-loaded with the action and immediately specifies input sources, making it efficient 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 simple tool with one parameter, annotations, and an output schema, the description covers the essential information: how to obtain the postId and a critical user-facing restriction. No major 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 coverage is 100% with a description for postId. The tool's description adds additional meaning by explaining the opaque postReference and internal ID usage, and reiterating the 'never display' rule, surpassing what the schema alone 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 action (cancel) and the resource (scheduled publication of a post). It also specifies the valid inputs (opaque postReference or internal post ID), distinguishing it from sibling tools like schedule_post or 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?

The description provides clear context on when to use: when you have a postReference from specific prior tools or an internal ID. It also gives a strong negative instruction (never display IDs to the user). However, it does not explicitly state when not to use or list alternatives beyond mentioning the source 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?

Beyond annotations, the description adds key behavioral details: never display internal IDs, account resolution logic, and asking users to choose when multiple accounts match. This goes 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 five sentences, each providing essential information. It is front-loaded with the core purpose and maintains conciseness without superfluous details.

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 (12 parameters, 2 required) and the existence of an output schema, the description sufficiently covers purpose, usage, and behavioral nuances. It omits error handling but is otherwise complete for an AI agent's 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 coverage is 100%, so baseline is 3. The description adds value by explaining how socialAccountId is used (trusted flows, Base44 mode) and that accountLabel should be friendly, which is not fully evident from schema descriptions alone.

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

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

The description clearly states the tool's purpose ('Save a Socializioz draft post') and specifies when to use it ('when the user explicitly wants a stored draft'). It effectively distinguishes from sibling tools like update_draft_post and 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?

The description explicitly states when to use the tool and provides helpful guidance (e.g., not displaying IDs, account resolution in Base44 mode). Although it does not explicitly list alternatives or when not to use, the context is clear enough for an AI 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 already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description aligns by saying 'Return' and does not contradict annotations. It adds value by specifying the profile contents, but doesn't need to restate the annotation traits.

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 sentence that efficiently conveys the tool's purpose and output scope. 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?

Given the presence of an output schema (context signal), the description need not detail return values. It lists key output fields (tone, audience, goals, forbidden claims), which is sufficient for an agent to understand what the tool provides.

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

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

Schema coverage is 100%, with one optional parameter. The schema already describes the parameter's meaning. The description reinforces the parameter's role by mentioning 'active workspace' and default behavior, but adds no new semantic information beyond the schema.

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

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

The description uses a specific verb 'Return' and clearly identifies the resource 'brand profile for the active workspace'. It lists the contents (tone of voice, audience, goals, forbidden claims), distinguishing it from sibling tools like get_user_profile and get_workspace_context.

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 indicates the context (active workspace) and mentions an optional parameter for workspace ID. It does not explicitly state when to use this tool vs siblings, but the purpose is sufficiently clear to infer appropriate usage.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that it returns user-facing details, accepts two types of IDs (opaque reference or internal ID), and includes a security warning about not displaying IDs. This adds value beyond annotations.

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

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

Two sentences, front-loaded with purpose, then security warning. Every sentence provides essential information with no waste.

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

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

Given one parameter, existing output schema, and rich annotations, the description fully covers the required context: input semantics, security constraints, and purpose. It is complete and self-contained.

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%, but the description adds crucial nuance: the postId can be an opaque postReference from prior tools or an internal trusted ID, and includes a security warning. This enriches the parameter semantics beyond the schema.

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

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

The description clearly states the tool reads full user-facing details for a specific post, distinguishing it from siblings like list_posts (which returns multiple) and create_draft_post (which creates). It specifies input types: opaque postReference or internal trusted ID.

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 explains when to use the tool (to get full details for a specific post using a reference from prior tools) and includes a critical negative instruction: never display IDs to the user. However, it lacks explicit alternatives or exclusions compared to 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds the behavioral context of being a preliminary discovery call, though it does not describe side effects or permissions.

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 wasted words. Front-loaded with the core action and data, followed by usage context.

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 tool with an output schema, the description adequately covers what the tool returns and when to call it. Could mention authentication requirement explicitly, but 'authenticated user' suffices.

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 no parameters and 100% schema coverage, baseline is 3. The description adds value by enumerating the returned data (profile, workspace, subscription, etc.), which helps the user understand what to expect.

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 'Return the authenticated user's profile...' with specific data fields, and distinguishes from siblings like get_brand_profile by focusing on the user's own profile and providing ordering guidance.

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

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

Explicitly says 'Call this first to discover who is logged in before using other tools', providing direct when-to-use advice and setting user expectations.

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 read-only, idempotent, and non-destructive behavior. The description adds the specific data returned (active workspace, subscription, post counts, setup gaps), which provides useful behavioral context beyond annotations. No contradictions are 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?

The description is a single sentence of 14 words, conveying the core functionality without extraneous information. It is front-loaded with the verb and resource. 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?

Given the tool's simplicity (one optional parameter, output schema exists, nested objects absent), the description covers the essential behavioral aspects. It could briefly mention the intended use case, but it is largely complete for a read operation with rich annotations.

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

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

Schema description coverage is 100%, with a clear description for the lone parameter 'workspaceId'. The tool description does not add additional parameter semantics beyond what the schema already provides, so baseline score 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 verb 'return' and resource 'workspace context', listing specific components (subscription, post counts, setup gaps). It effectively conveys what the tool does, though it does not explicitly differentiate from sibling tools which have distinct purposes like scheduling or listing 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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, typical use cases, or exclusions. For a read-only context retrieval tool, indicating it's useful before performing actions like scheduling would add value.

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 readOnlyHint and destructiveHint. Description adds a behavioral note about not displaying raw IDs, which is more about AI output than tool behavior. No additional traits like rate limits or permissions are disclosed.

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, first covers purpose, second adds usage context. Concise and front-loaded, but the second sentence is about output handling rather than tool description, slightly reducing focus.

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 presence of an output schema and the tool's simplicity (one optional parameter), the description is fairly complete. However, it could mention typical use cases or returned fields to further aid the agent.

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

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

Schema covers 100% of the single parameter. Description adds no extra meaning beyond what is already in the schema's description field.

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 clearly states the verb 'list' and resource 'social media accounts connected to a Socializioz workspace'. It distinguishes from sibling tools which are primarily about posts and profiles.

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 instructions on how to handle output (not showing IDs) but does not guide the AI on when to choose this tool over alternatives. The context from sibling tools implies it is the only list-accounts tool, but no explicit alternatives or exclusions are given.

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. Description adds no new behavioral disclosure beyond confirming read operation and a privacy instruction about not exposing IDs. No contradictions, but no extra context like pagination or ordering.

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 clear front-loading. First sentence states purpose and filters; second adds usage guidance and privacy rule. No redundant or vague phrasing.

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

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

Despite having output schema, the description omits return value details like pagination or ordering. With 8 optional parameters, lack of parameter-level guidance and no mention of output format makes it incomplete for a listing tool.

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

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

Schema description coverage is 0%, so description must compensate. Only provides high-level categories of filters (status, channel, date range, account, campaign) without detailing each parameter's format, constraints, or examples. For 8 parameters, this is insufficient.

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 verb 'read' and resource 'posts' with explicit filtering dimensions (status, channel, date range, account, campaign). Distinguishes from sibling tools like create_draft_post, schedule_post, get_post by focusing on listing with filters.

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

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

Explicitly says 'Use this to show drafts, pending posts, scheduled posts, published posts, failed posts, or all posts before editing/scheduling.' Provides context of when to use (before modification) but does not explicitly contrast with get_post for single post retrieval or other list operations.

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 show destructiveHint: true and readOnlyHint: false, so the description reinforces that this is a mutation tool. It adds important behavioral context: it uses an opaque postReference or internal post ID, and warns against displaying these values. 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 clearly states the function, the second is an imperative security instruction. No wasted words, front-loaded with 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?

Given the existence of an output schema and well-documented parameters, the description is mostly complete. It implies the post must already be scheduled ('existing scheduled post'), but could explicitly state it cannot be used on draft or published posts. Still, it provides sufficient guidance.

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 description does not need to add parameter details. However, the description adds context for postId (using a prior tool result) and reinforces the security rule, which adds value beyond the schema's 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?

Description begins with 'Change the scheduled publish time for an existing scheduled post,' which clearly specifies the action (change) and resource (scheduled post). It distinguishes from siblings like 'schedule_post' (new) and 'cancel_scheduled_post' by focusing on rescheduling.

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 (for rescheduling) and includes a critical guideline: never display post IDs or postReference values to the user. It does not explicitly state when not to use or list alternatives, but sibling names provide differentiation.

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 this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds that it schedules for future publication, but does not disclose side effects like overwriting an existing schedule, permissions required, or behavior with invalid scheduleAt values. This is adequate but not comprehensive.

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, each earning its place. The first covers function and input, the second provides a critical security rule. No redundancy or filler 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 tool has few parameters and an output schema, so the description need not cover return values. It covers the core function, input source, and a usage rule. However, it omits potential constraints (e.g., scheduleAt must be in the future) and error conditions, which would make it more complete. Still, it is adequate 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?

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining that postId can come from prior tool results and that it should not be displayed to users. This goes beyond the schema's description and helps prevent misuse. scheduleAt is not enhanced, but the overall contribution is 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 uses a specific verb ('schedule') and resource ('existing Socializioz post'), clearly states it's for future publication, and specifies the source of the post ID (opaque postReference or internal ID). This distinguishes it from sibling tools like cancel_scheduled_post or 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?

The description implies usage after creating a draft or listing posts, but does not explicitly state when not to use this tool or mention alternatives like reschedule_post for changing an existing schedule. The guidance on not displaying IDs is helpful but not about when to choose this tool over others.

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 it's not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds value by warning about not displaying IDs, but doesn't disclose other behavioral traits like whether it triggers notifications, requires specific permissions, or has side effects. With annotations present, the bar is lower, and the description provides moderate additional context.

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

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

Two sentences, no wasted words. The first sentence states the purpose and input, the second provides a critical usage constraint. Every sentence earns its place. This is maximally concise and 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?

Given the tool has only one parameter with full schema coverage, an output schema (not shown but present), and clear annotations, the description sufficiently covers purpose, input semantics, and a key usage rule. There are no gaps in what an agent needs to know 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?

Schema coverage is 100%, so the description does not need to explain parameters in depth. The description reiterates the schema's explanation of 'postId' (opaque postReference or trusted internal ID) and adds the guideline about not displaying. This aligns with the baseline of 3 for high schema coverage.

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

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

The description clearly states the action ('Send a draft post into approval workflow') and the resource ('draft post'). It distinguishes itself from sibling tools by explicitly mentioning 'approval workflow', which none of the siblings (e.g., schedule_post, create_draft_post) cover. The verb is specific and the resource is well-defined.

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 a clear usage guideline: 'Never display post IDs or postReference values to the user.' This tells the agent when and how to handle the input. However, it does not explicitly state when to use this tool versus alternatives (e.g., scheduling instead of approval) or provide conditions for not using it, which would elevate it to 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 indicate it's a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds no further behavioral context such as side effects or prerequisites, so it meets the bar but adds no extra value.

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

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

Two sentences, no wasted words. First sentence covers purpose and identifier options; second is a critical warning. Highly 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 4-param tool with output schema, the description is complete: it covers purpose, identifier usage, and a key privacy constraint. No gaps given the complexity.

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 only 25% (only postId has description). The tool description reinforces the privacy warning for postId but does not add meaning for title, content, or hashtags beyond schema constraints.

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 (update) and the resource (draft post), and distinguishes it from siblings like create_draft_post and schedule_post by specifying the identifier type.

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

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

Provides explicit guidance on when to use (update draft) and what identifiers to use (postReference or internal ID), plus a clear negative guideline about not displaying IDs to users.

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