PostPlanify

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: the effect is terminal for the post ('Cancelled posts cannot be rescheduled; a new post is needed instead'). It doesn't say whether the cancel is reversible or how the post's status/returns change, but the irreversibility disclosure is substantive.

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

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

Three short sentences, front-loaded with the action, then the precondition, then the consequence. No filler and every sentence carries information.

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

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

For a destructive one-param mutation with no output schema, the description covers the action, the eligibility constraint, and the downstream consequence. It leaves the precise resulting state of the post (deleted vs status change) unstated, a minor gap given annotations already signal destructiveness.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents postId fully. The description's mention of 'scheduled post' is consistent with the schema but adds no syntax or format detail beyond it — baseline 3.

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

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

States a specific verb+resource ('Cancel a scheduled post') and immediately scopes it to scheduled posts only, which distinguishes it from the sibling delete_post and edit_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 a clear precondition ('Only scheduled posts can be cancelled') that tells the agent when this tool is applicable versus other post-mutating siblings. It stops short of naming an explicit alternative or stating when-not-to-use beyond the scheduled-only restriction.

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 the write/open-world/non-destructive profile, and the description adds substantial context beyond that: scheduledAt must be a future ISO 8601 value, per-platform media requirements, carousel ordering, and Bitly-dependent link shortening. It stops short of describing post-creation outcomes or permission/failure behavior, so not a full 5.

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

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

Front-loaded main action followed by organized PLATFORM NOTES bullets; nearly every line earns its place. Minor redundancy exists where carousel order and boardId sourcing are restated relative to the schema, but overall it is efficient 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 15-param tool with nested objects and no output schema, the description covers the hard parts: required per-platform params, media sourcing, and scheduling constraints. It doesn't describe what the tool returns (e.g., the created post ID) or failure behavior, but the description needn't cover return values and the structured fields handle the rest.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds value by giving cross-tool provenance for socialAccountId/mediaIds and spelling out conditional requirements per platform (YouTube title, Pinterest boardId, Google Business EVENT/OFFER dates). This goes beyond what the schema alone conveys.

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+scope: 'Create and schedule a new social media post for one social account.' This clearly distinguishes it from siblings like edit_post, delete_post, and cancel_post without needing their 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?

Explicitly routes the agent to the right sibling for each dependency: socialAccountId from list_social_accounts, mediaIds from a named set of upload tools with conditions for each (ChatGPT attachments, local files, curl, public links), and boardId from list_pinterest_boards. Platform notes state exactly when special params become required, leaving little to inference.

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

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

Annotations only declare the mutation/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds genuinely new behavior: one-time URL, 15-minute expiry, 300MB ceiling, the exact multipart/form-data shape (fields entries then file last), and the returned uploadUrl/uploadId semantics. This is exactly the kind of operational context annotations cannot carry.

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?

Purpose, limits, and the three-step flow are front-loaded, and every clause carries operational weight. The inline curl example is dense but earns its place by pinning down the multipart ordering rule; it is the only slightly heavy element.

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

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

With no output schema, the description compensates by naming what comes back (uploadUrl, fields, uploadId) and how to consume it. Combined with the expiry, size, and format constraints, an agent has everything needed to execute the full upload flow without guessing.

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 documents fileName, mimeType, and size. The description still adds meaning the schema lacks: a 300MB cap that bounds the `size` parameter and the accepted-format scope behind the mimeType enum. The format list largely repeats the enum, so it is not a full 5.

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

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

States a specific verb+resource ('Get a one-time URL to upload a file from the user's device directly') and immediately bounds it with the 300MB limit and file-type scope. This distinguishes it cleanly from siblings like upload_media_from_url, upload_media_from_base64, and open_upload_box without needing to name 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?

Gives an explicit numbered workflow: call this, POST multipart to uploadUrl, then call finish_upload with the uploadId. That tells the agent precisely where this tool sits in the sequence. It stops short of explicitly stating when NOT to use it (e.g. server-side sources vs upload_media_from_url), so it is not a full 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The word 'Permanently' usefully reinforces irreversibility, but the description says nothing about side effects such as what happens to posts or comments referencing the deleted media, or whether authorization beyond the ID is required.

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

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

A single front-loaded sentence with the verb, resource, and key constraint; there is no filler and nothing to trim.

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

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

For a one-parameter destructive tool with annotations covering the safety profile and no output schema, this is nearly sufficient. The only meaningful omission is downstream impact on content that references the deleted media.

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% for the single mediaId parameter, so the baseline is 3. 'By its ID' adds no format, source, or validation detail beyond what the schema already states.

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 specific verb ('delete'), resource ('uploaded media file'), and lookup key ('by its ID'), which clearly separates it from delete_post and cancel_post in the sibling list. It stops short of explicitly naming an alternative, but the resource 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?

There is no when-to-use guidance, no prerequisites (e.g., ownership or workspace scoping), and no mention of alternatives such as list_media for locating the ID first. Usage must be inferred entirely from the tool 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the irreversibility guarantee ('cannot be undone'), which is genuinely useful context beyond the annotation. It stops short of permissions requirements or confirmation behavior.

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 the destructive nature and irreversibility front-loaded. Nothing wasted.

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

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

For a single-parameter delete tool whose annotations already carry the destructive/read-only profile, the description covers what an agent needs: the operation and its irreversibility. It omits what happens on a missing/invalid postId and any return confirmation, but no output schema exists to compensate.

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% for the single postId parameter, so the schema already documents it fully. The description adds no syntax, format, or sourcing detail beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb (delete) and resource (post), with the added qualifier 'permanently' that sharpens scope. It does not distinguish itself from the sibling cancel_post, which is the nearest plausible alternative for undoing a 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?

No guidance on when to use this versus cancel_post, no prerequisites, no mention of what conditions must hold before deleting. The usage is only implied by the name.

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 openWorldHint=true, so the risk profile is largely covered structurally. The description adds the useful constraint that only scheduled posts are editable, but says nothing about irreversibility, permission requirements, or side effects of editing a scheduled post (e.g., does it re-queue or reset approval).

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, each earning its place: purpose, eligibility constraint, and update semantics. Front-loaded with the action and 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?

For an 11-parameter mutation tool with nested objects and no output schema, the description covers the essentials (scope and partial-update behavior) but omits permissions, error conditions for non-scheduled posts, and any indication of the response. Adequate but with clear gaps given the tool's 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 description coverage is 100%, so parameter-level detail is already handled by the schema. The description still adds genuinely new semantics: the partial-update contract that only changed fields should be supplied, which governs how all 11 parameters are used and is not encoded in the schema itself.

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 ('Update a scheduled post') that clearly separates it from siblings like create_post, delete_post, and get_post. It is clear but does not explicitly name or differentiate itself from alternatives in the tool list.

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 a hard precondition ('Only scheduled posts can be edited') and PATCH-style guidance ('Only include the fields you want to change'), which meaningfully shapes invocation. It stops short of naming alternatives (e.g., use create_post for drafts) or stating what to do when a post is not scheduled.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is already covered. The description adds genuinely useful behavior beyond that: it discloses the return value (media ID), its role in the workflow, and the non-obvious carousel batching rule. It does not mention failure modes such as an expired or uncompleted upload, which would have earned a 5.

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

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

Three tight sentences, front-loaded with the precondition, then the return value, then the edge case. Every clause carries information an agent needs; there is 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?

With no output schema, the description correctly supplies the return value and its consumer (create_post), which is exactly what is missing from structured data. It is slightly incomplete on what happens if the upload never landed at the URL or the uploadId is stale, but for a one-parameter finalizer it is close to sufficient.

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

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

Single parameter with 100% schema description coverage; the schema already explains that uploadId is 'returned by create_upload_url'. The description restates the same provenance plus carousel ordering, adding little semantic depth beyond the schema, so the baseline 3 applies.

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

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

States a precise verb+resource ('finish upload'), names the prerequisite tool (create_upload_url) and the downstream tool (create_post), so it is distinguishable from siblings like upload_media_from_url or open_upload_box without opening any schema.

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

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

Explicitly defines the trigger condition ('After the file was uploaded to the URL from create_upload_url'), the required input, and the follow-up step ('pass to create_post'), plus the special carousel case with ordering instruction. The sequencing leaves nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely new context by disclosing the returned metric categories and the notable behavior that output is 'platform-specific data format', but it says nothing about permissions, rate limits, or whether a date range is implied or defaulted.

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 that are front-loaded with the core purpose and then the payload contents; no filler or repetition of the title. It could be tighter, but every sentence carries information.

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

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

With no output schema, the description correctly takes on the burden of describing return values, naming both account-level and post-level metrics plus the platform-specific format caveat. The remaining gap is routing context (time range or when to prefer get_analytics_trends), which is a modest omission for a two-parameter read tool.

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

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

Schema description coverage is 100% for both parameters, so the schema already explains workspaceId and socialAccountId. The description adds no parameter-level meaning (no ID format, no note that both are required, no scope caveats), which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('Get analytics data for a specific social account') and enumerates the metric families returned (followers/following, views/likes/comments/engagement rate). It is clear on its own, but it never distinguishes itself from siblings like get_analytics_trends or get_brand_overview, leaving the agent to infer which analytics tool to pick.

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?

There is no when-to-use or when-not-to-use guidance, and no mention of the two obvious alternatives in the sibling set (get_analytics_trends, get_brand_overview). The agent gets no signal about whether this is the per-account snapshot versus the trend or brand-level view.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds the return shape ('daily snapshots') and the scoping by day count, but says nothing about pagination, data freshness/latency, rate limits, or permission requirements for a read-only analytics 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?

Two tight sentences with the resource and return payload front-loaded and zero filler; nothing could be removed without losing information.

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

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

With no output schema, the description does the necessary work of stating what comes back (daily follower growth and engagement snapshots) and the time scoping. It is nearly complete for a read-only analytics tool; only freshness/latency and pagination behavior are unstated.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the days default (30) and max (365). The description only echoes the day-window concept ('specified number of days') without adding format or semantics beyond the schema, so the baseline 3 applies.

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

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

The description gives a specific verb+resource ('Get historical trend data for a social account') and names the concrete payload ('follower growth and engagement metrics over time'). It is clear enough to distinguish from a current-snapshot sibling like get_account_analytics by the word 'historical/over time', but it never names or contrasts that sibling explicitly.

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

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

Usage is only implied by 'over time' and 'historical' – an agent can infer this is for trend/backfill questions rather than point-in-time analytics, but the description gives no explicit when-to-use, when-not-to-use, or alternative (e.g. get_account_analytics).

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

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

Annotations already declare the safe-read profile (readOnlyHint, destructiveHint false, openWorldHint false), so the description only needs to add scope context — and it does, disclosing the fixed 7-day window, the set of connected accounts included, top 10 posts, and daily trend series. It stops short of noting freshness/latency or whether the window is configurable.

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

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

Two sentences, zero filler, with the purpose front-loaded and the content enumeration immediately after. Every clause earns its place by telling the agent what the aggregate contains.

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

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

With no output schema, the description does the work of explaining the return shape (accounts, 7-day metrics, top 10 posts, daily trends), which is exactly what an agent needs to judge applicability. Minor gaps remain around data freshness and whether the 7-day window can be adjusted.

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% for the single workspaceId parameter, so the schema already carries parameter meaning and the baseline of 3 applies. The description says 'for a workspace' but adds no format, source, or validity constraints beyond the schema.

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

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

States a specific verb and resource (aggregated analytics overview for a workspace) and enumerates the payload contents, which separates it conceptually from account-level siblings like get_account_analytics. It does not, however, explicitly name those siblings or state the workspace-vs-account distinction as a routing rule.

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

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

Usage is implied: reach for this when you need a broad workspace-level snapshot rather than per-account or per-post detail. There is no explicit when-to-use, when-not-to-use, or named alternative among the many analytics/list siblings, so the agent must infer the selection rule.

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 openWorldHint=false, so the safety profile is covered by structured data. The description adds that the target is the authenticated user and that this doubles as a connectivity check, but says nothing about what the response contains despite there being no output schema.

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, purpose first, usage second, with no 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?

For a trivial read-only, zero-parameter tool the description covers purpose and usage adequately. The one remaining gap is the shape of the returned profile, which neither the description nor an output schema supplies.

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

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

The tool takes zero parameters, so per the calibration this is the baseline of 4; there is simply no parameter semantics to explain.

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

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

States a specific verb and resource: 'Get the authenticated user's profile.' This is clearly distinguishable from sibling reads such as get_workspace or get_social_account, though it never names a sibling explicitly.

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

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

Gives concrete usage contexts ('verify the connection is working', 'get user context'), which is good guidance for a zero-parameter probe tool. It stops short of stating when-not-to-use or naming an alternative.

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 openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral value beyond that by explaining that `metrics` is null for unpublished posts or uncollected analytics, and that null differs from zero — a real interpretation hazard for the caller.

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: what is retrieved first, then the edge-case semantics. No filler, no repetition of the title or annotations.

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

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

With no output schema, the description carries the burden of describing returns and it does so well by listing the included fields and the null-metrics edge case. The only gap is not indicating where a valid postId comes from, which would help an agent chain calls 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 100% for the single postId parameter, so the baseline is 3. The description only alludes to 'a specific post' and adds no format, origin (e.g., from list_posts), or validity detail beyond the schema.

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

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

The description uses a specific verb ('Get') and resource ('a specific post'), then enumerates exactly what is returned (content, status, media, publishing logs, performance metrics). It is clearly distinct from list_posts by scope, but it never names a sibling or explicitly contrasts itself with tools like get_analytics_trends.

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

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

Usage is only implied: the agent can infer this is the tool for fetching one post's full detail by postId. There is no explicit 'use this when...' statement, no prerequisites, and no guidance on when to prefer it over get_account_analytics or get_analytics_trends for performance data.

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 openWorldHint=false, so the safety profile is covered by structured data. The description adds nothing beyond that – no error/not-found behavior, no auth or scope requirements, no indication of what 'details' are returned, and no output schema to compensate.

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 short sentence with no filler, and the resource is front-loaded after the verb. It is efficient, though it is arguably under-specified rather than maximizing the space available.

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

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

For a one-parameter read tool with full annotation coverage, the description is minimally viable. The gap is that with no output schema, the agent gets no sense of what fields 'details' returns or how a missing/inaccessible account is signaled.

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

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

Schema description coverage is 100% and the single accountId parameter is documented in the schema itself. The description adds no format, source, or acquisition guidance for the ID, so the baseline 3 applies.

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

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

Clear verb+resource: 'Get details about a specific connected social account.' The word 'specific' implicitly contrasts with the list_social_accounts sibling, but the sibling is never named, so differentiation is inferential 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as list_social_accounts or get_account_analytics. The agent must infer that this tool is for fetching one account by ID.

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 openWorldHint=false, so the safety profile is covered. The description adds only the scope of the payload (includes connected social accounts); it says nothing about lookup failures or how much 'detailed info' is returned. 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?

A single front-loaded sentence with no filler or repetition. It is efficient, though 'detailed info' is slightly hand-wavy and could be tightened.

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 read with no output schema, the definition covers the essentials. But the vague 'detailed info' leaves the returned fields under-specified, and no error behavior for a bad/missing workspaceId is given.

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% (workspaceId fully documented), so the baseline is 3. The description adds no syntax, format, or provenance detail for the ID beyond what the schema already states.

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

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

States a specific verb (get) and resource (workspace) plus the notable return content (connected social accounts), so an agent knows exactly what it retrieves. It does not, however, distinguish itself from the similar-looking list_workspaces sibling.

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?

There is no guidance on when to use this over list_workspaces, nor any precondition (e.g., knowing a workspaceId) or mention of the alternative. The 'specific workspace' phrasing implies a single-record lookup but leaves selection to inference.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint). The description adds two useful behavioral facts beyond that: results are only direct replies (not recursive threads) and LinkedIn URNs must be passed raw without URL encoding.

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, each carrying a distinct payload (what it returns, where the ID comes from, the URN encoding caveat). Purpose is front-loaded and there is 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?

For a single-parameter read-only tool with no output schema, the description covers purpose, input provenance, and the one real gotcha (URN encoding). No pagination or return-shape note, but nothing critical is missing 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning over the schema by telling the agent where the ID comes from and giving a concrete LinkedIn URN format example that the schema does not provide.

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

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

States a specific verb and resource with a scoping qualifier: 'direct replies to a specific comment'. This naturally separates it from list_comments and reply_to_comment, though no sibling is named explicitly.

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

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

Gives concrete provenance for the required input ('Use the `id` returned from list_comments as the platformCommentId'), which is exactly the context needed to call it. It does not state when-not to use it or name an alternative for threaded/nested retrieval.

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, openWorldHint=false, so the safety profile is covered. The description usefully adds that only top-level comments are returned and enumerates the returned fields (author, text, platform, post context, read/hidden state), which matters given there is no output schema. It does not mention pagination or rate-limit behavior.

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

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

Three tight sentences, front-loaded with what is listed and where it comes from, then return contents, then use case. No filler or repetition, and 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 read-only annotations, 100% schema coverage, and no output schema, the description supplies the missing return-shape information and use context. Pagination behavior is left to the schema, which is acceptable but the only remaining gap.

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

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

Schema description coverage is 100%, including enum values and defaults, so the schema carries the parameter burden. The description only echoes the platform set already enumerated in the schema and adds no syntax or format detail beyond it, making the baseline 3 correct.

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

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

States a specific verb and resource (list comments and reviews) scoped to a workspace, and names the exact platforms harvested. The phrase 'top-level comments' implicitly differentiates it from list_comment_replies, so an agent can tell the two apart without opening either schema.

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

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

Gives clear when-to-use guidance: triaging an inbox, or resolving a comment ID before replying (which routes toward reply_to_comment). It lacks any explicit when-not-to-use statement or a named alternative, 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, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description goes further and discloses ordering semantics (page 1 = most recent, returned oldest-to-newest) and the meaning of response fields (fromBusiness, type values, media in attachments) — real behavioral context 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?

Four compact sentences, front-loaded with the core purpose, then ordering, then field semantics, then the ID linkage. No filler, though the field-type enumeration is dense and verges on list-like rather than prose.

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

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

With no output schema, the description correctly compensates by explaining the response shape (fromBusiness flag, type enum values, attachments). Pagination limits come from the schema. It is close to complete; only the exhaustive type enumeration being duplicated inline could be trimmed.

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

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

Schema description coverage is 100%, so all three parameters are already documented (including page default 1 = most recent). The description largely restates that and adds only the provenance of conversationId, which the schema also states. 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?

States a specific verb and resource ('Read the messages in a direct message conversation') and implicitly distinguishes itself from the sibling list_conversations by explaining that the latter provides the conversationId. An agent can tell which of the two list_* tools it wants.

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

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

Gives clear chaining guidance ('Use the `id` returned from list_conversations as conversationId') and explains pagination ordering, so the agent knows how to enter the call. It does not explicitly state when *not* to use this tool or name an alternative for a different need, so it stops short of 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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely new behavior: the replyWindow/canReply/expiresAt 24-hour constraint, newest-first ordering, and an explicit privacy rule ('only summarize or quote them for the user who asked'). These are traits the agent could not infer from structured fields.

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

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

Content is front-loaded: identity and sort order first, then payload fields, then the reply-window caveat, then privacy and workflow guidance. It is somewhat dense across several sentences, but each carries information an agent needs, so waste is minimal.

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 8-parameter schema fully described, no output schema, and rich annotations, the description covers the remaining gaps: it enumerates the return fields (customer, preview, needsReply, assignee, replyWindow) and the reply-window semantics. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by explaining what needsReply actually surfaces ('conversations waiting on an answer') and clarifying that replyWindow semantics gate whether a reply is even possible. It stops short of describing search scope or pagination behavior beyond the schema.

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

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

States a specific verb and resource ('List private direct message conversations from Instagram and Facebook Messenger for a workspace, newest first'), plus the source platforms and sort order. It is clearly distinguishable from siblings like list_conversation_messages or list_comments.

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 a concrete workflow: 'Use needsReply to find conversations waiting on an answer, then list_conversation_messages to read one,' naming the follow-up tool and the condition that selects it. It does not state when NOT to use this tool or name a competing list tool, so it stops short of the top mark.

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 readOnly/destructive/openWorld, so the safety profile is known. The description adds real context beyond that: the scope difference between calls with and without workspaceId, and the meaning of the per-item 'source' field ('library' vs 'upload').

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 short sentences, front-loaded with the core purpose and then the branching semantics; no filler. Slightly dense in the middle sentences but every clause carries information.

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

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

No output schema exists, and the description compensates by describing the returned item's 'source' field and the two id families. Pagination is left to the schema's page/pageSize descriptions, which is reasonable for a 4-parameter read 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 baseline is 3, but the description adds cross-tool meaning beyond the per-parameter text: it explains the concrete result-set consequence of passing workspaceId and confirms that both id kinds are accepted downstream by create_post.

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

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

States a specific verb and resource ('List media that can be attached to posts') and implicitly distinguishes itself from upload_media_from_base64/upload_media_from_url/delete_media in the sibling set. An agent can tell what this returns 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 conditional guidance: include workspaceId to get the dashboard library plus API/MCP uploads, omit it to get only API/MCP uploads. It also notes both id kinds are valid in create_post, which frames when this tool is useful. It does not name a sibling alternative explicitly, so it stops short of 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the downstream linkage to pinterestParams.boardId, but says nothing about pagination, rate limits, or what a board record contains.

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 purpose is front-loaded and the follow-on usage note is kept to a single clause.

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

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

For a one-parameter read-only list tool with no output schema, the description covers what it returns (boards) and why the IDs matter, which is enough to call it correctly. Return field details are absent but not critical here.

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% for the single accountId parameter, so the baseline is 3. The description does clarify the semantics of the returned board IDs (usable as pinterestParams.boardId), which is modest added value beyond the schema but not parameter syntax or format 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 states a specific verb and resource ('List Pinterest boards') scoped to a Pinterest account, which cleanly separates it from list_posts, list_media, and list_workspaces. It does not explicitly name a sibling it competes with, so it stops short of a 5.

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

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

The second sentence supplies concrete context: 'Pinterest posts need one of these board IDs as pinterestParams.boardId,' which tells the agent this is a prerequisite step before creating a Pinterest post. There are no explicit exclusions or named alternatives, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnly, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: results are paginated, workspaceId is mandatory, and the null-vs-zero metrics distinction prevents a common misreading. It omits return ordering and total-count behavior, keeping it short of a 5.

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

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

Front-loads purpose, scope and pagination in the first sentence, then devotes the second paragraph solely to the non-obvious metrics option. Every sentence carries information; the enumeration of statuses is the only mild 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?

Nine parameters with a required workspace and no output schema—the description covers pagination, the required param, status vocabulary and the metrics payload well enough to call the tool correctly. It leaves the response envelope (items array, total pages) and default sort order undocumented, which a caller would want before building on the results.

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, and the description earns above that by explaining includeMetrics semantics and what a null metrics value means, which the schema alone does not convey. Status values are restated from the enum, adding little, and the to/from date-filter semantics are left entirely to the schema.

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

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

States a specific verb and resource ('List posts with filters') plus pagination and the required workspace scope. It distinguishes itself from the sibling get_post only obliquely ('instead of fetching them one at a time') rather than naming it, so an agent can infer the split but must do a little work.

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

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

Gives an explicit usage scenario for includeMetrics with a rationale ('compare how posts performed instead of fetching them one at a time'), which effectively routes the agent away from repeated get_post calls. It offers no guidance on when to filter by status/platform versus listing broadly, and no exclusions for the other list_* 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, destructiveHint=false, openWorldHint=false, so the safety profile is fully carried by structured fields. The description adds the return payload shape (IDs, platform types, names), which is genuinely useful, but discloses nothing further about auth, ordering, or rate behavior. Credit is modest because the annotations do most of the work.

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 action and scope, then the return payload, then the actionable next step. The platform enumeration is long but each token earns its place because no output schema exists to document the possible values.

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

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

With no output schema present, the description correctly takes on the burden of describing what comes back: account IDs, platform enum values, and names. Given a zero-parameter list tool this is close to complete; only ordering or whether unconnected accounts are excluded is left unstated.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The mention of returned account IDs is return-value semantics rather than parameter semantics.

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?

A precise verb+resource ('List all connected social media accounts') plus an explicit scope ('across all workspaces') and a concrete enumeration of returned fields. It implicitly contrasts with the singular sibling get_social_account, but never names it, so sibling differentiation is left to inference.

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

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

The final sentence gives a clear downstream use case — 'Use the returned account IDs when creating posts' — which tells the agent why and when to call this first. It stops short of an explicit when-not or a named alternative (e.g., get_social_account for a single account's detail), so it lands at 4 rather than 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the access-scoping fact ('workspaces the user has access to'); it says nothing about pagination, ordering, or return shape beyond the implicit ID mention. Adequate but thin on top of 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 short sentences, zero filler, with the core action stated first and the usage hint second. 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?

For a simple, annotation-covered, zero-parameter list tool with no output schema, the description covers purpose, scope, and motivation sufficiently. The only gap is the absence of a sibling contrast with get_workspace, which is minor here.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies a no-argument listing operation, and there is no parameter semantics to clarify.

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

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

States a specific verb and resource ('List all workspaces') and adds the clarifying synonym 'brands' plus the scope 'the user has access to'. It is clear what the tool does, though it does not explicitly contrast itself with the singular sibling get_workspace, so the agent must infer the plural/singular split.

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

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

Explicitly says when to use it: 'Use this to find workspace IDs needed for other operations like listing posts or social accounts.' This gives a clear motivating context and names downstream tools, but it never states an exclusion (e.g., when get_workspace is the better choice), so it stops short of full routing guidance.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds genuine value beyond that by disclosing side-effect scope: the change is internal to PostPlanify and not visible to the customer. No auth or rate-limit detail, but the external-impact clarification is meaningful.

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 waste; the core action is front-loaded and the scope caveat follows immediately. 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 single-parameter state toggle with full annotation coverage and a complete schema, the description is essentially sufficient. Only minor gaps (e.g., any error/not-found behavior) remain, and no output schema 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?

Schema coverage is 100% and the single conversationId parameter is already documented as 'Conversation ID returned by list_conversations'. The description adds no further parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Mark a direct message conversation as read') and names the product scope (PostPlanify). The effect is unambiguous, though it does not explicitly distinguish itself from siblings like reply_to_conversation or list_conversation_messages.

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

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

Usage is implied by the purpose: call it when a conversation should no longer appear unread. There is no explicit when/when-not guidance or reference to an alternative (e.g., there is no competing read-state tool named). Adequate but leaves routing to inference.

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

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

Annotations only supply the safety profile (readOnlyHint/openWorldHint/destructiveHint); the description adds the actionable behavioral context: file-type and size/count limits, the interactive handoff where the user uploads and then supplies media IDs, the requirement to pass IDs to create_post in carousel order, and the instruction not to use other upload tools for those files.

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

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

Front-loads the core purpose and constraints in the first sentence, then routes alternatives. Slightly dense with repeated emphasis on not using other upload tools, but every sentence carries decision-relevant information.

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

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

With no output schema and only minimal annotations, the description carries the full burden and does so: it explains the interaction flow, limits, exclusions, and the follow-up create_post call. An agent has everything needed to invoke and follow through correctly.

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

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

The tool takes zero parameters, so the baseline is 4. The description nonetheless documents the implicit inputs the agent must handle in the follow-up turn (media IDs in order), which is more than a bare no-parameter tool would provide.

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 action (show an upload box in chat) with scope details (images/videos/PDFs, 300MB, 20 files) and explicitly distinguishes itself from sibling tools like upload_attached_file and the other upload tools. An agent can route correctly without opening other 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 (files from user's device, not at a public URL, not yet in chat, or too large to attach) and when-not-to-use (files already attached in chat -> upload_attached_file). It also names the downstream step (create_post) and the required ordering, leaving nothing to inference.

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

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

Annotations only cover the safety profile (readOnly=false, destructive=false, openWorld=true); the description adds genuinely useful behavior beyond that: immediate publication, platform-specific length caps, the hidden-comment restriction, the brandReplied side effect on the parent comment, and the LinkedIn URN encoding quirk.

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 short sentences; the core action is front-loaded, then constraints, side effects, and the platform-specific gotcha follow in descending order of importance. 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?

No output schema exists, and the description compensates by disclosing the success side effect (brandReplied=true) and the key failure mode (hidden comments), so an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: per-platform character limits for message and the instruction to pass a raw, non-URL-encoded URN for platformCommentId on LinkedIn — details absent from the schema.

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

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

States a specific verb and resource ('Post a public reply to a comment') plus the scope ('on its originating platform'), which cleanly distinguishes it from siblings like create_post, edit_post, and list_comment_replies.

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 a clear usage condition: reply to an existing comment, with an explicit exclusion ('Cannot reply to hidden comments'). It does not name alternatives (e.g., list_comment_replies) or state what to do when replying is impossible, so it stops short of full routing guidance.

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

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

Goes well beyond the annotations: immediate delivery, irreversibility ("cannot be unsent"), a confirmation requirement, text-only constraint, per-platform character limits, and the 24-hour eligibility window. Annotations only give readOnlyHint=false/openWorldHint=true; the description supplies the operational risks an agent actually needs.

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

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

Four sentences, each carrying a distinct decision-relevant fact (what/irreversibility, format, limits, eligibility), with the risk warning front-loaded before the constraints. No filler or restatement of the name.

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

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

For a two-parameter, no-output-schema write tool, all call-critical information is present: preconditions, irreversibility, format and length rules, and the source of conversationId. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% (baseline 3), and the description adds real value on top by giving concrete length limits (Instagram 1000, Facebook 2000) and the "Text only" type constraint that the schema's generic "Must fit the platform's length limit" leaves unspecified. It says nothing about conversationId beyond the schema's own pointer to list_conversations.

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 ("Send a direct message reply") on a specific resource (Instagram/Facebook conversation), and the "direct message" qualifier cleanly separates it from the sibling reply_to_comment. An agent can identify the tool 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 a strong gating precondition ("Only works while replyWindow.canReply is true (within 24 hours of the customer's last message)") and a procedural instruction ("confirm the wording with the user first"). It never explicitly names reply_to_comment as the alternative for non-DM cases, so routing between the two reply tools is left slightly to inference.

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

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

Annotations already declare the safety profile (not read-only, non-destructive, closed-world), so the bar is lower. The description still adds real context the annotations cannot: supported formats, the returned media ID, and the once-per-file/carousel sequencing. It does not cover auth or rate-limit behavior, but the return value and workflow details are valuable.

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

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

Front-loaded with the critical 'ChatGPT only' scoping constraint, and every sentence carries routing or workflow information. Minor redundancy: upload_media_from_url is named twice (once as a client alternative, once for public links).

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

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

There is no output schema, and the description compensates by stating the return value (a media ID attachable to a post) and detailing the carousel handoff. For a one-param write tool with full schema coverage, nothing essential is missing.

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

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

Schema coverage is 100% and the single nested 'file' object is fully documented (file_id, download_url, file_name, mime_type), so the schema carries the parameter burden. The description adds no field-level syntax or constraints beyond it, making the baseline 3 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?

States a specific verb+resource (upload an attached file/image or video) and a precise scope (ChatGPT only). It distinguishes itself from sibling upload tools by name, so an agent can route without opening any schema.

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

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

Explicitly says when to use (ChatGPT attachments) and when not to, naming three alternatives (open_upload_box, create_upload_url, upload_media_from_url) with the condition that selects each. It also specifies per-file invocation and the carousel workflow that feeds create_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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) by disclosing the 7MB size cap, supported formats, that the file is stored byte-for-byte with no compression or resizing, and that a media ID is returned. These are non-obvious behavioral facts an agent needs before committing to this path.

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

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

Front-loads the 'last resort' framing, follows with a compact ordered alternative list, then two short sentences of constraints and return value. Every sentence earns its place with 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?

With no output schema, the description supplies the return value (media ID attachable to a post), the size limit, the accepted formats, and the storage semantics. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the parameters are already fully documented, including the MIME enum. The description's format list (JPEG, PNG, GIF, WebP, MP4, MOV, PDF) essentially restates the enum rather than adding syntax or format guidance beyond it. Baseline 3 applies.

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

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

States a specific verb+resource ('upload a file sent as a base64-encoded string') and immediately positions it against named siblings. A reader knows exactly what it does and why it exists as a distinct tool.

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

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

Explicitly labels itself a 'last resort' and gives a prioritized ordering of five alternatives with the condition selecting each (attached file, shell commands via create_upload_url + finish_upload, user picking files, public URL). This is the strongest possible usage 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?

Annotations already declare this is a non-read-only, open-world, non-destructive write. The description adds real behavioral context beyond that: it fetches from an external URL over the network, enumerates accepted formats (JPEG/PNG/GIF/WebP/MP4/MOV/PDF), and tells the agent the operation returns a media ID for later use. It omits size limits, auth requirements, and failure modes for unreachable URLs.

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

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

Front-loaded with the core action, then formats, then downstream usage. Minor redundancy: the workflow's step 2 'Note the returned media ID' restates the preceding sentence about using the returned media ID when creating posts. Still tight overall.

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

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

With no output schema, the description correctly explains that a media ID is returned and how to consume it, plus accepted formats. For a two-parameter upload tool this is near-complete, though practical limits (file size, URL accessibility, auth) are unstated.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the 'public URL' constraint and the filename fallback rule. The description only reinforces that the source is a public URL and never mentions the optional filename parameter, so it adds nothing over the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Download a file from a public URL and upload it to PostPlanify') and scopes it to media for posts. The phrase 'primary way to add images and videos' implicitly separates it from the sibling upload_media_from_base64, which handles the other input source.

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

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

Gives clear context (adding media for use in posts) and a 3-step workflow ending in create_post. It never explicitly states when to prefer upload_media_from_base64 over this tool, so the base64 alternative is left to inference rather than named.

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