Publora

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds substantial non-obvious behavior: the snapshot does not reserve quota and writes are re-checked, publishNow consumes monthly quota without occupying the scheduled queue (even while processing), and a full queue does not block Publish Now when quota remains. It also explains how quotas are broken out (scope/units, connections breakdown).

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 and the primary use case are front-loaded, and each following sentence carries a distinct quota-modeling rule. It is dense but not padded; the middle sentences on queue semantics are long and could be tightened slightly.

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-required-parameter read tool with no output schema, the description covers what the response contains (quotas with scope and units, connections breakdown, queue usage) and the limits of that data (non-reserving snapshot). Nothing an agent needs to interpret or trust the result 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 baseline is 3; the description still adds meaning by tying scheduledTime to the batch's monthly quota period and clarifying that omitting it means 'Publish Now', which the schema only phrases as 'current period'. Not a full 5 since the format details live entirely in the schema.

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

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

States a specific verb ('Read') and a precisely enumerated resource set: plan, available features, publishing quotas, schedule horizon, all scoped to 'the current personal API actor'. It explicitly distinguishes itself from company_list_contexts for the Agency/Company case, so an agent can route without opening either schema.

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

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

Gives concrete triggering conditions ('before a batch of posts or after a quota/feature error'), a decision rule for the parameter ('Omit it for Publish Now'), and names the alternative tool for the company scope. When-to-use, when-not, and alternative are all present.

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

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

With annotations covering safety flags, the description still adds substantial context: it leaves the post in draft, demotes scheduled posts, never publishes, downloads/validates/stores bytes immediately, and deduplicates retries for the same post/file ID for 24 hours. It also enumerates formats and size ceilings (25MB images, 150MB video), which is behavioral information no annotation carries.

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 is front-loaded in sentence one and every sentence carries operational content, but the block is dense and packs URL rules, format limits, state changes, follow-up steps and dedup into one long run of text without visual grouping. Slightly heavier than necessary, though nothing is wasted.

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

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

For a mutation tool with nested parameters, no output schema, and destructive side effects, the description is complete: it explains input resolution, validation, storage, resulting post state, limits, and how to verify the result via get_post. An agent has everything needed to call it correctly.

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

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

Schema coverage is 75% and the description meaningfully supplements it: it explains that 'file' is a ChatGPT-supplied reference resolved via openai/fileParams, gives a hard constraint on download_url ('never invent... sandbox path/base64'), and explains fileName's SEO override purpose. Only the idempotencyKey semantics are left largely to the schema description.

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 first sentence states a precise verb and resource: 'Attach one image or video from ChatGPT to an existing personal post.' It distinguishes itself from create_post (attachment to an existing post), complete_media (explicitly declared unnecessary), and update_post without requiring the agent to open 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?

It states when to use it, when not to (don't invent a download URL, don't pass sandbox/base64 as a URL), the fallback path ('use a real public mediaUrls URL or upload local bytes'), and the follow-up path ('verify with get_post and schedule separately only if requested'). Alternatives such as complete_media are named explicitly.

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 mutating, non-idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds genuinely non-obvious context: the token is private material and must travel in the JSON body, never in a URL or routine summary. It does not say what state changes on success or what happens if the token is already consumed/expired, which keeps it off 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?

Two sentences, zero waste, with the action and its ownership scope front-loaded before the token-handling constraint. Nothing is repeated from the title or schema.

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?

Single-parameter tool, no output schema, and annotations carry the mutability profile, so the description need not explain return values. It covers what the agent must get right — whose invitation, and how to pass the secret — leaving no call-blocking ambiguity.

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 64-hex pattern already documented, so the baseline is 3. The description goes beyond that by governing how the single parameter must be transmitted (JSON only, never a URL) and reinforcing its private nature, which is real usage-relevant semantics the schema cannot express.

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

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

Specific verb (accept) + resource (Company invitation) with an explicit scope qualifier: the authenticated user's *own* emailed invitation. That scope distinguishes it from company_invite_member, company_resend_invitation and company_revoke_invitation without naming them, though a direct sibling callout would make it 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 triggering condition is clear: the user has received an emailed invitation and holds a token for their own acceptance. It implicitly excludes acting on other people's invitations. It does not name alternatives (e.g. resend vs. revoke when the token is missing/expired), so a small gap remains.

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?

Although annotations already declare destructiveHint=true and idempotentHint=true, the description adds valuable behavioral context: data is retained, unstarted scheduled posts are moved to drafts, the default Workspace is excluded, and no restore operation exists. It also reinforces retry behavior with the identical body and idempotencyKey. This goes well beyond restating 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 compact and front-loaded: it states the operation and side effect first, then constraints and operational guidance. Every sentence contributes either differentiation, safety context, or retry behavior.

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 workspace-archive tool with no output schema, the description covers the essential operational details: retention behavior, side effects on scheduled posts, default Workspace exclusion, lack of restore, commandVersion use, and idempotent retry. Nothing critical is missing for an agent to call it correctly.

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

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

Schema description coverage is high at 80%, so the schema already documents most parameters. The description reinforces expectedCommandVersion and idempotencyKey usage, but it largely repeats the schema's idempotency guidance and does not explain the required 'reason' parameter. Baseline 3 is appropriate when the schema carries most parameter meaning.

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: 'Archive an Agency Workspace.' It also names the important side effect, moving unstarted scheduled posts to drafts, which distinguishes it from generic workspace operations and from post-level tools in the sibling 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?

It gives clear usage context and constraints: the default Workspace cannot be archived and no restore operation is available. It also says to confirm the selected workspace and use its commandVersion. It does not explicitly compare this with an alternative archive/delete pathway, so it falls short of a full when/when-not/alternatives statement.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds real consequence context by stressing this changes the publishing gate, not just a notification. It also reinforces safe retry behavior for a lost response. It stops short of stating permission requirements or exactly what state the post is left in after the approval gate is removed.

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

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

Three short sentences, front-loaded with the action and its consequences, followed by the usage restriction and the retry rule. No filler and nothing buried.

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

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

With no output schema and full schema coverage, the description does what remains: explains the irreversible-ish consequence and the idempotent retry rule. It could still tell the agent what a successful response changes or whether the approval can be re-requested afterward, which matters for a destructive gate-changing mutation.

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 both ID parameters plus the idempotencyKey are fully documented in the schema. The description only restates the retry-the-identical-key rule already present in the idempotencyKey description, adding no new parameter semantics. 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 pair and resource with both concrete effects: removes the client approval requirement and revokes the review link. An agent can distinguish it from company_request_post_approval and company_get_post_approval 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?

"Use only when the user explicitly asks" is an explicit precondition that rules out speculative use, which is meaningful for a destructive tool. It does not name the sibling alternatives (e.g. request_post_approval) that would be used instead, so it falls short of a full routing 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 destructiveHint=true and idempotentHint=true; the description goes beyond them by explaining the retry contract for pending results and the real side effect that changed media invalidates client approval. It also documents a post-condition (thumbnail becomes ready auxiliary media requiring selection in YouTube settings). It stops short of describing the response shape or failure modes, which matters since there is 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?

Four tight sentences, front-loaded with the action and its precondition, then consequences and follow-up. The telegraphic phrasing ('Agency upload', 'retry complete, not reserve') is efficient but slightly cryptic on first read.

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, idempotent mutation with 100% parameter coverage and annotation support, it covers preconditions, retry semantics, side effects on approvals, and a downstream step. Only permission/auth requirements and the shape of the 'pending' result are 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?

Schema coverage is 100% and all three IDs are documented in the schema with the 'never a personal platformId' warning. The description adds nothing about any individual parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Complete a reserved Agency upload') plus the precondition ('after the HTTP PUT'), which separates it from company_reserve_media. The 'Agency' qualifier hints at the boundary with the sibling complete_media, but that distinction is never made 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?

Gives clear trigger conditions (after reserve + HTTP PUT) and an explicit routing rule away from an alternative: 'A pending result means retry complete, not reserve.' It also imposes ordering against downstream tools ('finish uploads before requesting review or scheduling'), though those siblings are described rather than named.

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, and readOnlyHint=false, but the description adds non-obvious behavior on top: absent status/scheduledTime/mediaUrls fields, backend platform-specific length validation, silent skipping of unsupported targets, firstComment null-clears-on-update semantics, and the exact retry contract (identical body and idempotencyKey) on a lost response. This is substantial value beyond the annotation set.

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 and the sibling exclusion, then ordered workflow steps. Every sentence carries information, though the single dense paragraph stacks several distinct concerns (draft shape, media, scheduling, verification, retry) without visual separation.

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 nested, 3-required-parameter mutation with no output schema, the description covers the entire lifecycle: draft creation scope, channel key sourcing, media reservation, scheduling handoff, and post-creation verification. Nothing an agent needs to call it correctly and recover from failure 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 67%, and the description compensates by explaining the two most error-prone parameters: draft.platforms must be exact channel keys (empty list = channel-less draft) and draft.firstComment takes one object with optional platform *types* rather than channel keys, with null clearing it. It does not clarify idempotencyKey generation beyond the retry rule or workspaceId sourcing beyond the schema note, so it stops short of full 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?

"Create an Agency draft without scheduling or publishing" gives a specific verb, resource, and explicit scope boundary. The follow-up "Personal create_post is not interchangeable" names the sibling it must not be confused with, so an agent can disambiguate 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?

The description routes the agent through the whole workflow: channel keys from company_list_channels, media via company_reserve_media/company_complete_media, then company_schedule_post, and verification via company_get_post. It also states a negative condition (personal create_post is not interchangeable) and notes unsupported targets are skipped rather than erroring.

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, idempotentHint=true, destructiveHint=false): explains that events are delivered externally to active receivers, that there is no immediate test send, that the one-time secret must be stored securely and not repeated, and that retries must reuse the identical body and idempotencyKey. These are the exact operational details an agent cannot infer from structured fields.

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

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

Front-loads the core action and event scope, then layers prerequisites and safety notes. Dense but nearly every sentence carries actionable information; only the secret-handling sentence is slightly advisory rather than definitional.

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 usefully notes that a one-time secret is returned and how to handle it, and it covers permissions, limits, and retry behavior for this mutating tool. It stops short of describing the full response shape or error behavior, but is sufficient for correct invocation.

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

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

Schema coverage is only 33% — workspaceId and idempotencyKey are documented in the schema, while url, name, and isActive are not. The description compensates partially by implying the event values and the URL safety/approval requirement, but says nothing about name length or the isActive flag, so it does not fully close the coverage gap.

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

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

States a specific verb (Create), resource (Workspace subscription/webhook), and event scope (post.published/post.failed). An agent can immediately distinguish this from company_update_webhook, company_delete_webhook, and company_list_webhooks by the creation action and the event set.

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

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

Gives clear preconditions: settings permission required, an approved public HTTP(S) receiver, backend destination-safety validation, and a 10-subscription cap. It does not explicitly route to a sibling for modifying or listing existing subscriptions, so the when-not/alternatives guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, and the description adds actionable meaning on top: the post-call context refresh requirement and the exact lost-response recovery rule (retry the identical body and idempotencyKey, never mint a new key). It does not cover permission/role requirements or what a stale expectedCommandVersion produces, which keeps it at 4.

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

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

Three short sentences, front-loaded with purpose, then prerequisites, then failure handling — nothing redundant. The phrasing is telegraphic ("Use the Account commandVersion ... and a reason") and harder to parse than it needs to be.

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 five-required-parameter mutation with no output schema, it covers the essential operational context: where the command version comes from, the required reason, the mandatory context refresh, and idempotent retry. Missing are authorization expectations and what a version-conflict response looks like, so not fully complete.

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

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

Schema description coverage is 60%: accountId, idempotencyKey and expectedCommandVersion are already documented in the schema, and the description largely restates them (commandVersion source, idempotency retry rule). The undocumented parameters, name and reason, get no added meaning beyond their length constraints. 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 ("Create an Agency client Workspace"), which separates it from sibling reads like company_get_workspace_context and mutations like company_rename_workspace or company_archive_workspace. It does not explicitly name a sibling or say what it is not, so it stops just 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?

Gives concrete preconditions and sequencing: take the Account commandVersion from company_list_contexts, supply a reason, and refresh context afterward. That is real routing guidance rather than implied usage. It lacks an explicit "do not use this when..." exclusion, so a 4 rather than a 5.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds genuinely non-obvious behavior: the attachment is detached rather than permanently purged, storage cleanup is delayed, and existing client approval is invalidated requiring a fresh review. That is exactly the consequential side-effect information an agent needs before calling a destructive tool.

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

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

Four short sentences, front-loaded with the action and the most surprising behavior (delayed cleanup), then consequences, then a safety caveat. Slight redundancy: the final 'Never supply a personal media ID' repeats a constraint already present in every schema property description.

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

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

For a 3-parameter destructive mutation with no output schema, the description covers the important ground: what is actually removed, that cleanup lags, and that approval state is affected. It does not say what the call returns or whether the post must be a draft at call time, which are the remaining minor gaps.

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

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

Schema description coverage is 100% and every parameter already documents 'Exact ID returned by a Company tool; never a personal platformId'. The description's 'Never supply a personal media ID' reinforces the same rule but adds no new meaning about workspaceId, postGroupId, or mediaFileId, so the baseline 3 applies.

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

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

States a specific verb ('Detach') and a precisely scoped resource ('a selected attachment from an Agency draft'), which is more accurate than the tool name's 'delete'. The 'personal media ID' caveat implicitly separates it from the personal-account delete_media / prune_media_reference siblings, so an agent can route 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?

Clear operating context: this is for Agency drafts, and after changing media the agent must request a new review since approval is invalidated. It gives a hard constraint ('Never supply a personal media ID') but never explicitly names the alternative tool (delete_media, prune_media_reference, company_list_post_media) or the condition that selects it, leaving that 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 destructive=true, idempotent=true and readOnly=false, so the safety profile is covered. The description adds real value beyond that: the eligibility window (draft or eligible failed post only), the confirmation requirement, and the retry contract on a lost response — behavior an agent would otherwise have to guess at.

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 action and scope before the exclusion and the retry note. No filler, though the idempotency sentence partially duplicates the schema text rather than adding new 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 only three fully-described parameters, rich annotations and no output schema, the description covers eligibility, exclusion and failure-retry behavior. It doesn't state whether deletion is irreversible or what a success response contains, which would be the final piece for a destructive operation.

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 postGroupId, workspaceId and idempotencyKey are all fully documented in the schema. The description's retry sentence restates the idempotencyKey guidance already present in the schema rather than extending it, so the baseline 3 applies.

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

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

States a specific verb (delete) and resource (Agency draft or eligible failed post) and immediately carves out the excluded scope: published posts on social networks. That contrast with the sibling delete_post / social-network deletion path lets an agent distinguish it without opening the schema.

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

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

Explicitly says when NOT to use it (published posts) and adds a pre-call instruction to confirm the selected post. It stops short of naming the exact alternative tool for published-post deletion, but the exclusion plus eligibility framing gives a clear 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 flag destructiveHint=true and idempotentHint=true, and the description adds value beyond them: the concrete consequence (notifications stop flowing), the permission prerequisite, and the exact retry protocol. It doesn't state whether the deletion is reversible or what the response contains, but against rich annotations this is strong.

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

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

Three short sentences, front-loaded with the action and its effect, then prerequisites, then the failure-recovery rule. No filler, and each sentence carries distinct information.

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

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

For a destructive, idempotent mutation with no output schema, the definition covers permission requirements, user confirmation, and retry semantics. Missing only the return shape and reversibility, which are minor given the annotation coverage.

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 webhookId, workspaceId, and idempotencyKey are fully documented in the schema, making 3 the baseline. The description restates the idempotencyKey retry rule and hints at confirming webhookId but adds no new syntax or format meaning beyond the schema.

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

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

States a specific verb and resource ('Delete a Workspace webhook subscription') plus the effect ('stop future notifications through it'), which separates it from create/update/regenerate-secret siblings in the webhook cluster. It never names an alternative explicitly, so sibling differentiation is implied by the verb rather than stated.

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

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

Adds real operational context: settings permission required, confirm the selected subscription, and retry the identical body/idempotencyKey on a lost response. It lacks an explicit routing statement such as 'to change a webhook's URL use company_update_webhook instead', which is the only gap.

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 idempotentHint=true, so the description earns credit for adding the *consequence*: it can revoke provider access and affects future publishing, which is real context beyond the flags. The retry instruction reinforces idempotency behavior, though it largely restates the idempotencyKey schema note and says nothing about what happens to already-scheduled posts.

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

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

Two tight sentences with zero filler: the destructive consequence is front-loaded, followed by the identification prerequisite and retry rule. Every clause 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?

For a destructive, no-output-schema mutation, the description covers the risk profile, the prerequisite lookup, and safe retry semantics. It stops short of describing downstream effects on existing scheduled/approved posts, which would fully close the loop for an irreversible operation.

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 (including the strict 24-hex pattern and the idempotencyKey constraints) are already documented. The description's only addition is the workflow hint to source the channel from company_list_channels, so the baseline 3 applies.

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

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

States a specific verb and resource ("Disconnect a selected social channel from the Workspace") and clearly distinguishes the target object (a channel/connection) from the connection-link siblings by pointing to company_list_channels for identification. 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 concrete prerequisite — confirm the exact channel via company_list_channels before calling — which routes the agent through the right preparatory tool. It does not explicitly name what to do instead when a channel should merely be re-linked rather than disconnected, so exclusions are only implied.

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

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

Annotations already cover idempotency and non-destructiveness; the description adds the meaningful nuance that this both creates and reuses an existing link, which is exactly the behavior a retry depends on. The security note (share only with the intended client) and the uncertain-result recovery path add real context. It stops short of describing token lifetime or what the returned link 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?

Three short sentences with zero filler; the purpose and the security caution come first, and the sibling routing comes last. 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, idempotent, non-destructive tool with a fully documented schema, the description covers purpose, safety, and failure recovery. The one gap is that there is no output schema, so a word about the returned link (URL form, expiry/reusability) would have completed the picture.

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%, with the schema itself warning 'never a personal platformId'. The description adds no further meaning about workspaceId, so the baseline 3 applies.

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

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

States a specific verb (generate or reuse) and a specific resource (a private Workspace link for connecting client channels). The closing sentence explicitly routes the agent away from company_get_connection_link and company_rotate_connection_link, so it is distinguishable from the three tightly-related siblings.

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

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

Gives a concrete safety rule ('Share only with the intended client') and an explicit error-path instruction ('After an uncertain result use company_get_connection_link, not rotation'). It lacks a general statement of when to prefer generate/reuse over an explicit rotate, but the routing it does provide is actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral detail beyond those annotations, especially the pagination rule ('follow nextCursor with unchanged filters') and compatibility-oriented approval-field opt-in.

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 compact sentences front-load the core read/range operation, then cover filters, pagination, and approval opt-in without 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 9-parameter read tool with strong safety annotations and no output schema, the description covers the essential date range, filtering, and pagination behavior. It leaves the limit parameter's role and the return payload shape unaddressed, so it is strong but not fully complete.

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

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

Schema description coverage is 78%, and the schema already documents cursor, channelKey, workspaceId, from/to, and includeApproval semantics. The description restates some of those parameter meanings and omits limit entirely, so it adds limited value 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 ('Read'), resource ('Agency Workspace calendar'), and scope ('within a UTC date range'), with filters clarifying the operation. It does not explicitly contrast the tool with sibling alternatives such as company_list_posts or company_get_post, so it falls 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?

Explains optional status/channelKey filtering, cursor continuation with unchanged filters, and includeApproval opt-in behavior. It gives clear usage context but names no alternative tool or when-not condition.

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, idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds meaningful context the annotations cannot: the link grants connection authority, is not a client portal, and must not be replaced by provider tokens.

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 action, then the security cautions. No filler, though the middle sentence is slightly dense with two distinct warnings.

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 and no output schema, this is nearly complete. It could say what happens when no link exists, but the security-critical behavior is covered.

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

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

Schema coverage is 100% and the single workspaceId parameter is documented with a pattern and a warning against personal platformIds. The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific verb and resource: 'Read the Workspace's existing private client connection link.' The word 'existing' implicitly separates it from the generate/rotate/revoke siblings, but it never names them, so an agent must infer the boundary.

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 handling guidance ('Share only with the intended client', 'never pass provider tokens to MCP') but no explicit routing such as 'use generate_connection_link if no link exists yet.' Usage context is implied by 'existing' rather than stated.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, but the description adds useful context about what the read returns: ownership-transfer state, eligible members, and commandVersion. It also explicitly reassures that the call performs no transfer, reducing the risk of confusion with the mutation sibling.

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

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

Two concise sentences front-load the read purpose and immediately clarify the key non-mutating behavior. There is no redundant or wasted language.

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 operation with comprehensive annotations, the description gives enough context to call it correctly and even names key returned data. It does not describe the full response shape, but the essential behavior and return categories are covered.

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

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

The single accountId parameter is fully described in the schema, including its format and the warning not to use a personal platformId. The description does not add syntax or meaning beyond that, so the baseline 3 for high schema coverage 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 opens with a specific verb and resource: reading the Account ownership-transfer state, eligible members, and commandVersion. It also distinguishes the read from the sibling mutation tool by stating that this read does not transfer anything.

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

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

It clearly frames this as the read-only inspection path and notes the Owner-only constraint on actual transfers, which helps an agent choose it when checking state before a transfer. It does not explicitly name company_transfer_ownership as the mutation alternative, but the distinction is still clear.

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

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

Annotations already cover readOnly, idempotent, and non-destructive traits, so the bar is lower. The description adds valuable scoping context ('These rules apply to Agency posts, not personal posting tools'), which is behavioral information beyond annotations. It does not describe the return format, but for a read-only lookup this is a minor gap.

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

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

Two short sentences with zero waste; the usage instruction and scope exclusion are front-loaded and easy 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 zero-parameter read tool with no output schema, the description explains the general nature of the returned data ('publishing formats and platform rules') but not its shape or structure. An agent knows why to call it but not quite what to expect back.

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. No parameter semantics are needed or missing.

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 ('Read') and resource ('supported Company publishing formats and platform rules'), which is distinct from sibling tools like company_get_workspace_context or account_context. It does not explicitly name a sibling, but the scoping to Agency posts adds useful differentiation.

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

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

Explicitly says to read this 'before preparing content or media,' giving a clear usage timing. Also provides a when-not exclusion: 'not personal posting tools.' Lacks explicit naming of an alternative tool, but the context is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes further by disclosing deferred publishing semantics, firstCommentResult state values, and that acceptance is not delivery. That is meaningful context beyond the structured hints, though auth/permission requirements are not covered.

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

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

Three dense sentences, all doing work, with the core read action front-loaded. Some jargon (outcomeUnknown, firstCommentResult) is packed in without explanation, but no sentence is wasted.

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

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

No output schema exists, and the description usefully enumerates the notable returned fields and their state values. A read tool with full annotation coverage and full schema coverage is adequately served, though return shape details are only partial.

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 workspaceId/postGroupId descriptions already carry the ID-provenance warnings. The description restates includeApproval's opt-in behavior, adding little new syntax or format detail, so baseline 3 applies.

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

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

States a specific verb and resource ("Read full Agency post detail") plus scope details (publishing deferrals, comment results). It distinguishes itself from company_get_post_summary by emphasizing "full" detail, though it does not name the 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 directions: "inspect outcomeUnknown before any manual comment" and "Verify writes here; asynchronous acceptance does not mean delivery." It lacks explicit routing between the several other post-reading siblings (company_get_post_summary, company_list_posts, get_post), which keeps it from 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds important behavioral context beyond them. It discloses that the tool returns a private bearer review link and warns not to share it autonomously or treat presence of a link as client approval, which is valuable safety information for an agent.

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 tightly written sentences with no wasted language. The core purpose is front-loaded, followed immediately by the critical manual-sharing and no-inference warning.

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 read-only tool with complete schema descriptions and full safety annotations, the description supplies the missing behavioral and return-value context. It identifies what is returned, the permission scope, and the key restriction on using the returned link, leaving no critical gap 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 description coverage is 100%, so both required parameters, workspaceId and postGroupId, are already well documented in the schema. The description adds no parameter-specific syntax, constraints, or format details beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 read operation: retrieving a post's current client review details and notification status, with the added return of a private bearer review link. This clearly distinguishes it from approval-mutating siblings such as company_request_post_approval, company_cancel_post_approval, and company_retry_approval_notification.

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

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

It gives clear usage context: this is a read-only manager-permission operation, and the returned link is for manual sharing only. It explicitly says not to autonomously send the link or infer client approval, which is a strong when-not guideline. However, it does not explicitly name sibling alternatives for requesting, canceling, resending, or retrying approvals.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that the read is scoped to a workspace/channel; with no output schema it does not explain what the "totals" actually break down by.

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

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

A single sentence, front-loaded with the resource and scope, with no filler. 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?

For a two-parameter read tool with no output schema, the description should say what the totals contain (e.g., counts grouped by post status). Naming the resource is not quite enough to predict the return shape.

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 schema descriptions already explain both the channelKey provenance and the workspaceId format, so the description adds essentially nothing new. Baseline 3 is appropriate when the schema does all 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 ("Read post status totals") plus the scope (one Agency Workspace), which separates it from single-post readers like company_get_post. It stops short of naming a sibling alternative to sharpen the distinction.

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 phrase "optionally for a channelKey," and it points at company_list_channels as the source of that value, which is useful guidance. However, nothing says when to prefer this over company_list_posts or get_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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and idempotency profile is fully covered by structured data. The description adds the sequencing context (fetch options before choosing settings) but says nothing about what the call actually returns, latency, or failure modes when a connection is stale.

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, front-loaded with the purpose and followed by the prerequisite. Every clause carries information the agent needs; there is no filler or restatement of the title.

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

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

There is no output schema, so the description carries the burden of telling the agent what comes back — and it only gestures at 'privacy and interaction settings' without indicating the fields or shape of the creator options. Combined with no mention of what happens when the TikTok connection lacks those permissions, it is adequate but leaves a real gap for a tool whose return value is the whole point.

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 both parameters already carry a pattern plus the warning that they are exact Company-tool IDs, so the baseline would be 3. The description goes one step beyond by naming the specific source tool for the connection id (company_list_channels), which is actionable provenance the schema does not supply.

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

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

The description uses a specific verb ('Read') and a specific resource ('current TikTok creator options for a Workspace connection'), which is unambiguous among siblings — no other tool retrieves TikTok creator options. It does not explicitly name a sibling it might be confused with, but the resource is distinctive enough that the agent can distinguish it without opening the schema.

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

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

It states a clear usage context ('before selecting privacy and interaction settings'), which tells the agent this is a prerequisite read step rather than an end action. It also routes the agent to company_list_channels for the connection id. It stops short of explicit exclusions (e.g., when not to call, or behavior for non-TikTok connections).

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, idempotent, non-destructive, closed-world), so the description is free to add what they cannot: that this is a prerequisite step before mutating actions and that the data can go stale, requiring a refresh. It stops short of describing the returned shape (e.g. how capabilities are enumerated) or error behavior on an invalid workspaceId.

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 imperative sentences, each earning its place: what it reads, the constraint against role-name inference, and the refresh trigger. The most important instruction sits first with zero preamble.

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-required-param, no-output-schema read tool, the description covers purpose, timing, and staleness — enough to invoke it correctly. A small gap remains: it doesn't say whether the returned 'commandVersion' must be passed to subsequent write tools, which would matter for an agent chaining calls.

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 both parameters already carry the strong 'exact ID returned by a Company tool; never a personal platformId' guidance plus a 24-hex pattern. The description adds no additional parameter meaning, 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 names a specific verb ('Read') and a specific resource ('one Agency Workspace's current role capabilities and commandVersion'), which is far more precise than the title's restatement. It implicitly separates itself from account/ownership siblings by scoping to a single workspace's role capabilities, though it never names a sibling tool 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?

It gives real usage conditions: read this 'before acting', refresh 'after a conflict or workspace change', and the explicit anti-pattern 'Never infer permissions from a role name'. That is strong temporal guidance, but no alternative tool is named as a fallback or contrast point.

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

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

The annotations already disclose that this is a non-read-only, open-world, non-idempotent operation. The description adds valuable behavioral context beyond annotations: the owner-only constraint for admin invitations, the need to confirm recipient and grants, and the uncertain-delivery guidance not to resend blindly. It does not cover rate limits or invite expiration behavior, but it meaningfully supplements the annotations.

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

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

The description is compact and front-loaded: it opens with the core action, then adds permission, confirmation, and failure-handling guidance. Every sentence contributes operational value with no wasted exposition.

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 four-parameter mutation tool with open-world behavior and no output schema, the description covers the essential invocation context: what it does, who can do it, what to confirm, and what to do after uncertain delivery. It omits return-value details and invite lifecycle behavior, but those gaps are secondary 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 description coverage is only 25%, so the description must compensate for undocumented parameters. It does add meaning for email and workspace grants, and clarifies that only an owner may invite a company admin, but it does not explain accountId, accountRole beyond the admin case, or the roleSlug options. The schema handles enums and patterns, but the description only partially fills the coverage gap.

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

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

The description states a specific verb and resource: sending an Agency team invitation with explicit client workspace grants. It is clearly distinct from sibling tools like company_resend_invitation and company_accept_invitation, and the mention of company_list_team further clarifies the intended workflow.

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

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

The description gives useful usage context: owner-only permission for inviting a company admin, confirmation of recipient and grants, and a caution against blindly resending after uncertain delivery in favor of inspecting company_list_team. It stops short of explicitly stating when to use company_resend_invitation versus this tool, so it is strong but not fully exhaustive.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety basics are covered. The description still adds real value beyond them: a data-completeness caveat ('not a complete post editing history'), pagination behavior (opaque nextCursor), and an explicit instruction to treat returned event content as data rather than instructions. The only gap is no mention of the result limit ceiling.

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 what the tool reads and immediately followed by the scope caveat, then pagination and safety notes. No sentence is filler; each one carries a distinct fact.

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, non-destructive list tool with no output schema, the description supplies the essentials an agent needs: permission scoping, workspace filtering, cursor opacity, and prompt-injection hygiene. The absence of any statement about the default or maximum page size is the only meaningful omission.

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 50%, with accountId and workspaceId documented in the schema but limit and cursor bare. The description compensates for the cursor by declaring it opaque, and reinforces workspaceId's scoping effect, adding meaning beyond the field descriptions. It leaves limit's range and role unexplained, so it falls short of full 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?

States a specific verb and resource ('Read existing Company administrative audit events') and scopes the result as permission-bound. It also pre-empts a likely misconception by noting this is not a complete post editing history, which sharpens what the tool actually returns. It does not risk confusion with any sibling, since none of the listed tools is an audit-log reader.

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

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

It gives a prerequisite ('within your permissions') and a concrete usage hint that optional workspaceId scopes events to a client, but never states when to reach for this tool versus alternatives or when it should not be used. Usage is implied rather than prescribed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive/closed-world, so safety is covered. The description adds value beyond that by disclosing the response container (data.items) and that an empty result is legal, which prevents an agent from treating 'no channels' as an error.

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 clauses with zero filler, front-loaded with the purpose and then the ID-field routing rules. Every sentence carries an actionable instruction an agent would otherwise get wrong.

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, so the description does the necessary work of naming the return envelope and the two key fields (channelKey, id). It stops short of describing the other item fields or ordering, but an agent has enough to call and consume the result 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% and the single parameter already documents the 24-hex pattern and the 'never a personal platformId' constraint. The description only reinforces that it must be a Workspace ID; it adds no new syntax or validation detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List one Workspace's connected channels') with scope and even the return envelope (data.items, possibly empty). It distinguishes itself from the personal-list sibling by warning against list_connections IDs, though it does not mention the plausibly closer sibling company_get_platforms.

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 downstream guidance: 'Copy channelKey verbatim into draft.platforms; use id for disconnect and creator-info,' plus a hard exclusion ('Never substitute personal list_connections IDs'). What's missing is the condition that would select this over company_get_platforms or company_get_platforms-like alternatives.

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 this as a safe, idempotent, closed-world read, so the bar is lower. The description still adds real context beyond them: what is returned (capabilities, Account commandVersion) and an access constraint an agent would otherwise learn only by failing — that personal tools cannot reach Company posts.

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 routing instruction 'Start here for Agency work', so the most decision-relevant line comes first. Slight cost: 'Account commandVersion' is capitalized oddly and is dense jargon that an agent may not parse without 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?

With no parameters and no output schema, the description carries the whole informational load and does so: it says what is listed, what accompanies each entry, how to use the results, and who should not use it. Nothing essential to calling this discovery tool correctly is missing.

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

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

There are zero input parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The sentence about using exact returned IDs is about outputs consumed by siblings rather than a parameter, which is a mild bonus.

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 accessible companies/workspaces, plus what each entry carries (current capabilities and Account commandVersion). It also positions itself as the entry point ('Start here for Agency work') and implicitly contrasts with the personal-side tools, though it never names a specific sibling like account_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?

Usage is clearly directed: 'Start here for Agency work', use exact returned IDs downstream, and corporate employees should use personal tools for their own posts. It gives both a when-to-use and a when-not-to-use signal, but the alternative (account_context) is referred to only generically as 'personal tools' rather than by 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 readOnlyHint, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely non-obvious behavioral context: it returns readiness state, and a successful upload does not by itself mean the media is ready. It omits return shape and whether results are paginated, but the readiness caveat is real added 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 compact sentences with the core action front-loaded and no filler. The second sentence is terse to the point of being slightly cryptic, but it carries important warning content rather than waste.

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

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

For a two-parameter read-only list tool with fully documented params, this is close to sufficient. However, with no output schema, the description introduces the concept of 'readiness' without saying what readiness fields or states come back, which is the main thing an agent would need to interpret the response.

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 both parameters carry their own 'never a personal platformId' documentation, so the schema does the heavy lifting. The description's 'Company media IDs only' cautions about ID provenance but does not map clearly onto the two declared parameters (workspaceId, postGroupId), leaving a small mismatch. Baseline 3 applies.

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

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

States a specific verb and resource: read saved media and readiness for a single post. It is distinguishable from siblings like company_get_post or company_list_posts, though the shift from the name's 'company' to the description's 'Agency post' introduces mild terminology ambiguity about which entity scope applies.

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 gives a usage constraint ('Use Company media IDs only; a successful upload alone does not prove completion') but never names an alternative tool or states when to use this versus company_get_post or attach_media. Usage is implied rather than routed.

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, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new context: cursor scoping to caller and workspace, the requirement to keep filters stable across pages, and that includeApproval is opt-in for backward compatibility. Return shape is still undescribed, keeping it below top marks.

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

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

Three dense sentences with zero filler; the core action and scope come first, followed by optional filters and then pagination rules. Every sentence contributes information an agent needs.

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

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

For a 7-parameter read tool with no output schema, the description covers filtering, opt-in fields, and pagination discipline, which is most of what a caller needs. It omits page-size semantics (limit bounds are only in the schema) and any hint at the result shape, a minor but real 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 71%, so the schema carries most of the weight, and the description mostly restates the same filters (status, approvalStatus, channelKey, includeApproval). It does add the useful semantic point that approvalStatus operates independently of publishing status, but limit and workspaceId get no added meaning. Baseline 3 fits.

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 posts") and constrains scope emphatically to ONE Agency Workspace, which implicitly separates it from the account-wide list_posts sibling. It never names a sibling explicitly (e.g. company_get_post for a single post), so it stops short of full differentiation.

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 solid pagination guidance (follow nextCursor with unchanged filters, cursor scoped to caller and workspace) but says nothing about when to prefer this over list_posts or company_get_post, nor any prerequisites such as membership in the workspace. Usage is implied rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description correctly spends its words elsewhere: it discloses the required authorization level (Owner/Admin) and carries a substantive caution ('Never infer permission from a role name alone'). That permission caveat is behavior an agent cannot get from the schema or annotations.

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

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

Three short sentences, front-loaded with the resource scope, then the optional-parameter trigger, then a warning. Nothing is redundant and the ordering matches how an agent reads it.

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

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

With no output schema, the description does enough by naming the returned entities (members, invitations, available actions) and the permission context. It stops short of describing pagination or result shape, but for a small two-parameter read tool that gap is minor.

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 50%: accountId is documented in-schema, while includeWorkspaceGrantEditing has no schema description. The description compensates by explaining that the flag yields membership versions and workspace choices, which is exactly the missing semantic. accountId's 'never a personal platformId' rule is already handled in the schema.

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

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

States a specific verb ('Read') and enumerated resources (Account members, invitations, available actions), so the agent knows exactly what data comes back. It does not explicitly differentiate itself from the near-neighbor sibling company_list_workspace_members, leaving scope disambiguation 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?

Provides the precondition 'as Owner/Admin' and a conditional trigger for includeWorkspaceGrantEditing, which is useful usage context. However, it offers no explicit exclusion or named alternative (e.g. use company_list_workspace_members for workspace-scoped member lists), so routing between siblings remains implicit.

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, idempotent and non-destructive, so the bar is lower; the description still adds real value by disclosing the permission requirement and the security guarantee that signing secrets are never returned. It stops short of describing result shape (e.g., which fields a subscription carries) or paging 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 short sentences, purpose first, then permission, then the two caveats. Nothing is repeated and no sentence is 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 with full schema coverage and read-only annotations, the description covers scope, auth and the key security caveat. With no output schema, a brief note on what a listed subscription contains (URL, events, active state) would have closed the 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 coverage is 100% and the single parameter already documents the 24-hex ObjectId format and the 'never a personal platformId' constraint. The description only reinforces the workspace scoping ('one Workspace's') without adding format or sourcing 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 gives a specific verb and resource ('List ... signed publishing webhook subscriptions') and scopes it to a single Workspace, which separates it from the create/update/delete/regenerate webhook siblings. It does not explicitly name the sibling that handles personal subscriptions, only noting they are 'separate', so routing is implied rather than stated.

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

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

'Requires Workspace settings permission' is a concrete prerequisite an agent must check before calling, and 'personal subscriptions are separate' steers away from an out-of-scope use. There is no explicit when-not guidance or named alternative tool for the personal case.

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, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral context beyond annotations by indicating the permission context for Workspace Managers and the importance of membership versions, though it does not describe return shape or pagination.

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 compact sentences front-load the core purpose and then add role/version guidance. There is no filler or redundant restatement of the tool 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 simple two-parameter read tool with rich schema descriptions and strong annotations, the description is mostly complete. It names the returned entities and version guidance, but with no output schema it could say a bit more about the returned membership/candidate structure.

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 schema itself explains that accountId and workspaceId must be exact Company-tool IDs rather than personal platformIds. The description adds only the scope phrase 'one Agency Workspace' and does not supplement parameter meaning beyond the schema.

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

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

The description gives a specific verb and resource: reading members and eligible existing-member candidates for one Agency Workspace. It is clear enough to distinguish this as a workspace-membership read, but it does not explicitly name sibling alternatives such as company_list_team or company_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?

It states a concrete usage context: Workspace Managers use this view for permitted grant changes, and it points to returned membership versions for those changes. It does not provide explicit exclusions or compare against sibling tools, so it falls short of 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 destructiveHint=true and idempotentHint=true, so the description isn't carrying the safety profile alone. It still adds real context: the non-deletion of the personal account, the optimistic-concurrency requirement on membership version, and a recovery step ('inspect the team after an uncertain response'), though it stops short of stating permission requirements or what a conflict response looks like.

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 scope limit, then the verification advice. Nothing is redundant with the sibling names or the schema.

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 three-parameter mutation with annotations covering safety and no output schema, the definition covers action, side effects, concurrency, and a post-failure check. A minor gap is the absence of guidance on what to do for a stale expectedVersion beyond the schema's 'refresh after a conflict' note.

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 baseline is 3; the schema already documents all three parameters with ID patterns and version sourcing. The description reinforces that the version is the 'current' membership version but adds no format or conflict-resolution detail beyond what the schema says.

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 ('Remove a member's Company access') and immediately bounds the blast radius ('does not delete their personal Publora account'), separating it from invite/revoke-invitation siblings. An agent knows exactly what this tool mutates 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?

Usage is implied by the offboarding framing plus 'Confirm the selected member and inspect the team after an uncertain response', which is operational advice rather than selection guidance. It never names alternatives such as company_revoke_invitation (pending invites) or company_transfer_ownership, so the agent must infer when this tool is preferred over those.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=false; the description still adds operational value by stating the draft is separate and unpublished, that published parts are excluded from recovery, and that a lost response must be retried with an identical body and key. It does not cover what happens to existing media references or any permission requirements, keeping it below 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?

Four short sentences, each carrying a distinct constraint: what is created, what is excluded, that it does not publish, and the retry procedure. Front-loaded with the action and zero 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 still signals that the return value is a draft that should be inspected before further action. It is adequate for a three-parameter mutation, with only the omission of permission/authorization expectations and the draft's composition (which media carry over) as remaining gaps.

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

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

Schema coverage is 100%, so all three parameters (including the 24-hex ID format and idempotencyKey charset/length rules) are already fully documented in the schema. The description only restates the retry-on-identical-key rule, which the schema also states, so it adds little beyond the structured data.

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

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

Specific verb and resource ('Create a separate draft WITH media') plus a precise source scope ('confirmed failed Agency post targets'). It distinguishes itself from generic creation by the recovery framing and the 'Published parts are never recovered' boundary, though it never names the sibling it is contrasted with (e.g. company_create_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?

Clear context for use: only for confirmed failed Agency post targets, never for published parts, and explicitly not a scheduling/publishing action. Missing an explicit routing statement against alternatives like company_create_post or company_reschedule_post, so it stops short of 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 only declare destructive/idempotent flags; the description goes further by explaining exactly what is destroyed (the previous secret becomes invalid), that the new secret is returned one-time only and must be saved immediately, and how to recover from a lost response by replaying the identical body and key. That is precisely the extra context the annotation bar asks for.

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 ordered by importance: what it does, what it requires, how to handle the result and retries. Every clause carries actionable information 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 carries the burden of explaining the return value, and it does so explicitly (one-time secret to be saved and propagated to the receiving service). Permission requirements and failure/retry behavior are also covered, leaving nothing an agent needs to call it correctly 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 idempotencyKey retry rule. The description restates the retry-with-identical-key behavior, adding slight reinforcement but no syntax or meaning the schema lacks, 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?

"Replace the Workspace webhook's signing secret, invalidating the previous secret" gives a specific verb (replace) and a narrowly scoped resource (webhook signing secret), which separates it from siblings like company_update_webhook, company_create_webhook, and company_delete_webhook 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?

Adds real gating context: "Requires settings permission and explicit intent," telling the agent both the permission prerequisite and that this shouldn't be fired casually. It stops short of naming alternatives (e.g., update_webhook for non-secret changes) or stating when-not-to-use, so it lands just under 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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), it discloses the optimistic-concurrency requirement (current commandVersion), the post-call obligation to refresh context, and the exact lost-response retry procedure. It does not say whether the rename is reversible or what happens on version mismatch, leaving some destructive-mutation behavior implicit.

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, front-loaded sentences with no filler: operation, precondition, follow-up, and failure handling in that order. Every sentence carries actionable 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 six-parameter destructive mutation with no output schema, the description covers preconditions, state-change follow-up, and idempotent retry, which is most of what an agent needs. It omits permission/role requirements and the consequence of a stale commandVersion, which would round out the destructive-operation picture.

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 67%, and the description only adds meaning for two of six parameters: it clarifies expectedCommandVersion is the current Workspace commandVersion, and reiterates identical-body/key retry for idempotencyKey. Nothing in the description explains name, reason, accountId, or workspaceId semantics, so it adds modest value over 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 ("Rename an Agency Workspace") with the key precondition ("using its current Workspace commandVersion"), which cleanly separates it from siblings like company_create_workspace or company_archive_workspace. An agent can identify the operation without opening the schema.

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

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

Gives concrete operational guidance: use the current commandVersion, refresh context afterward, and on a lost response retry the identical body and idempotencyKey. It stops short of naming when to prefer an alternative (e.g. archive vs rename) or any role/permission prerequisites, so it is clear context but not full when/when-not 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?

The description adds substantial behavioral context beyond the annotations: approval does not publish or schedule automatically, the returned bearer link is for manual sharing only, and the agent must not infer client approval or send the link autonomously. It also explains idempotent retry behavior on lost responses, which is exactly the kind of operational detail an agent needs.

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

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

The description is dense but front-loaded, moving from purpose to prerequisites, invalidation rules, publishing behavior, link handling, and retry guidance. Every sentence carries operational value 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 mutation tool without an output schema, the description covers the key context: required role, preparation steps, invalidation conditions, non-publishing behavior, returned review link handling, and idempotency. An agent has enough information to invoke and handle the result 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%, so the parameter meanings are already documented in the schema. The description reinforces the idempotencyKey retry rule but does not add meaning beyond the schema for workspaceId, postGroupId, or managerComment.

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 outcome: request a new client review round as Manager. It clearly positions the tool around approval review rather than publishing, scheduling, or checking approval status, which distinguishes it from nearby approval and post tools.

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

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

It gives strong prerequisites: save draft edits and finish media uploads first, and it explains that later content or publishing-setting changes require a new review. It does not explicitly name sibling alternatives such as canceling or checking approval, but the usage context is clear.

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

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

Adds real value beyond annotations: it discloses that approval/media/state gates still apply and how to recover from an ambiguous failure. However, annotations mark this destructiveHint=true and the description never explains what destructiveness means here (e.g., whether prior approvals or scheduled metadata are invalidated).

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 tight sentences with zero filler, front-loading the action, then the constraints, then verification, then retry. Every sentence carries operational 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 directs verification to company_get_post, and all four required parameters are schema-documented. The remaining gap is the post-mutation state outcome (approval status, what a success response conveys).

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 schema already explains postGroupId, workspaceId, scheduledTime format, and idempotencyKey rules. The description only adds the 'user's agreed UTC instant' intent, which is minor incremental meaning over a fully documented 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 ('Change the publishing time of a scheduled Agency post') plus the target semantics (UTC instant). It is distinguishable from company_schedule_post by the 'scheduled' qualifier, but that sibling is never named, so differentiation relies on 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?

Gives clear operating context: existing permission/state/media/approval checks still apply, verify the result with company_get_post, and retry with the identical body on a lost response. It stops short of explicitly contrasting with company_schedule_post or company_unschedule_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?

Annotations already state destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds important behavioral context beyond those annotations: the prior token is invalidated, delivery may be uncertain, and company_list_team should be inspected before retrying. It does not describe permissions, rate limits, or response shape, but the key side effects 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 compact sentences with no wasted wording. The action and side effect are front-loaded, followed immediately by the confirmation and retry caveat.

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 mutation with rich annotations and no output schema, the description covers the important behavioral takeaway: resending invalidates the old token and retrying requires inspection first. It could additionally mention required permissions or expected success behavior, but the essential calling context is present.

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 both required parameters are documented as exact Company IDs that must not be personal platformIds. The description adds no parameter-specific syntax or meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: resend a selected Agency team invitation by email. It also clarifies the side effect of invalidating the previous token, which distinguishes it from a plain invite. It does not explicitly contrast with company_revoke_invitation or company_invite_member, so sibling differentiation is implicit rather than stated.

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

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

It gives concrete usage guidance: confirm intent before calling, and inspect company_list_team after uncertain delivery before retrying. This covers the main risky scenario for a non-idempotent resend. It does not explicitly say when to choose this over revoke_invitation or invite_member, but the context is clear.

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

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

The description adds substantial behavior beyond the annotations: upload must use the returned uploadUrl and ALL uploadHeaders with no API key, followed by company_complete_media. It also explains lost-response retry semantics and the idempotencyKey requirement, consistent with idempotentHint=true and destructiveHint=false.

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

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

The description is dense but front-loaded and every sentence carries operational value: reservation purpose, upload mechanics, completion step, thumbnail constraints, and retry behavior. There is no redundant restatement of the name or schema.

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 mutation tool with no output schema and partial schema descriptions, the description covers the critical workflow, upload headers, completion step, thumbnail constraints, and response-loss retry behavior. It leaves some general parameter and response details unspecified, but is largely sufficient to invoke the tool correctly.

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

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

Schema coverage is only 38%, but the description compensates for several key fields by specifying purpose=youtube_thumbnail, type=image, JPEG/PNG, size and dimension constraints, and Company IDs only. It still does not explain fileName or fully document general type/contentType/size behavior outside the thumbnail case.

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: 'Reserve an upload for an existing Agency draft.' It also distinguishes the reservation step from the follow-up company_complete_media call and clarifies the YouTube thumbnail use case.

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

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

It gives clear usage context: reserve for an existing Agency draft, then PUT bytes and call company_complete_media. The YouTube thumbnail path is explained well, but there are no explicit exclusions or direct comparison to alternatives such as get_upload_url or attach_media.

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

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

Adds substantial context beyond annotations: no idempotencyKey, never resends an already-sent notification, creates no review, and the non-deterministic failure mode where a lost delivery acknowledgement produces an uncertain result. This is exactly the behavioral detail the non-idempotent annotation alone would not convey.

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

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

Three tight sentences, front-loaded with the action and immediately followed by the key constraints and the recovery path. No filler or restatement of the title.

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

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

For a non-idempotent mutation with no output schema, it covers the critical gaps: what it does not affect (no review created), its no-double-send guarantee, and how to verify the result via company_get_post_approval. An agent has everything needed to invoke it safely.

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 both parameters are fully documented in the schema (exact IDs, never a personal platformId). The description adds no parameter-level syntax or format detail, so it earns only the baseline for a well-documented two-param 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 ('Retry the client-decision notification') plus the recipient ('requesting manager'), which is enough to distinguish it from adjacent approval tools like company_request_post_approval and company_resend_invitation. It also pre-empts confusion by noting it 'Creates no review'.

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 operative guidance: inspect notificationStatus via company_get_post_approval afterward, and warns 'do not retry blindly' because a lost acknowledgement leaves an uncertain outcome. It names the follow-up alternative but does not explicitly contrast this with other approval-related siblings an agent might pick.

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 idempotentHint=true; the description adds the concrete consequence ('the old URL will stop authorizing connections') and a confirm-intent guardrail. It stops short of stating irreversibility or required permission level.

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, effect stated before the follow-up advice — well front-loaded. The phrase 'inspect ... after uncertainty' is slightly awkward and costs a bit of clarity.

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 mutation with no output schema and rich annotations, the description covers effect, caution, and a verification path. A note on irreversibility would close the last 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 coverage is 100% and the single workspaceId is fully documented in the schema, including the 'never a personal platformId' warning. The description adds nothing about the parameter, so 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 ('Revoke') and resource ('Workspace's client channel connection link'), plus the effect on the artifact. It is distinguishable from company_rotate_connection_link and company_disconnect_channel by wording, but never names those siblings 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 a confirmation instruction and points to company_get_connection_link for verification, which is real usage guidance. It does not say when to choose revoke over rotate, regenerate, or disconnect_channel — the choices an agent will actually face.

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 idempotentHint=true, so the safety profile is covered structurally. The description adds useful behavioral context by explaining that the token becomes unusable and recommending verification through company_list_team after an uncertain response.

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 tight sentences with the main action and effect front-loaded. Every clause contributes either to the action's purpose or to post-call verification.

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 but idempotent revoke operation with full schema coverage and no output schema, the description is largely complete: it states the effect and gives a recovery/verification path. It could say more about permissions or expected response behavior, but annotations carry much of that burden.

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 accountId and invitationId are already documented with precise ID constraints. The description adds only implied context that the invitation should be pending, but no parameter-level 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, 'Revoke,' and a specific resource, 'pending Agency team invitation,' and states the effect that the invitation token can no longer be accepted. This clearly distinguishes it from siblings such as company_resend_invitation or company_accept_invitation.

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

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

The description implies the tool applies to pending invitations and gives one useful post-call instruction: inspect company_list_team after an uncertain response. However, it does not explicitly state when to choose revocation over alternatives like resending or accepting an invitation, so usage guidance is only minimally viable.

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

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

The description discloses concrete destructive behavior ('invalidating the previous URL') beyond the destructiveHint annotation, and it addresses non-idempotency by advising to read company_get_connection_link after an uncertain response before retrying. This adds valuable context for a mutation tool.

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

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

Three short sentences with no waste: the core action and effect are front-loaded, followed by a confirmation cue and a recovery step. 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 destructive, non-idempotent mutation with a single well-documented parameter and no output schema, the description covers what it does, what gets destroyed, the need for confirmation, and how to recover from uncertain outcomes. 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 description coverage is 100%, so the single parameter is fully documented in the schema. The description does not add any new meaning about workspaceId beyond what the schema already provides, making 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?

The description states a specific verb and resource ('Replace a Workspace's private channel connection link') and adds the key effect ('invalidating the previous URL'), which distinguishes it from generate (create a new link) and revoke (remove a link) siblings.

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

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

It gives clear operational guidance: 'Confirm intent' before use and 'After an uncertain response read company_get_connection_link before another rotation.' However, it doesn't explicitly state when to choose this over revoke_connection_link or generate_connection_link, leaving some selection inference to the agent.

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

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

Annotations only declare the flag profile; the description adds genuinely new behavior: delivery is asynchronous, verification must go through company_get_post, and a lost response requires retrying the identical body and idempotencyKey. Preconditions (draft approval, media completion, current client approval) are also stated, which annotations do not convey. Nothing contradicts the destructive/openWorld/idempotent hints.

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

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

Four tight sentences with no filler: action first, then prerequisites, then the publish-now exception, then delivery/retry semantics. Every sentence carries operational information an agent needs before calling.

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, open-world mutation with no output schema, the description covers gating, async delivery, retry safety, and where to confirm the result. The only real gap is that it never indicates what the immediate call returns (e.g., a post ID or a pending status), leaving the agent reliant on company_get_post alone.

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 four parameters are already documented in-schema, including the exact UTC ISO format and the identical-key retry rule. The description restates the publish-now time semantics and the retry rule without adding syntax or accepted-value detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource — 'Schedule an Agency post' — plus the gating condition ('after draft approval and an agreed time'). It implicitly separates itself from company_reschedule_post/company_create_post by requiring an approved draft, but never names those siblings, so an agent must infer the distinction from tool names alone.

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 prerequisites ('Save edits and finish media first; required client approval must be current') and an explicit branch for the publish-now case. It also routes verification to company_get_post. It stops short of naming when to use company_reschedule_post or company_create_post instead, so the boundary against siblings remains implicit.

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

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

Adds meaningful behavioral context beyond annotations: roleSlug null removes the grant, expectedVersion is an optimistic-concurrency guard sourced from team/workspace-members views, and the caller should refresh after a conflict. These details align with the destructiveHint=true and idempotentHint=true annotations rather than contradicting them.

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

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

Two tight sentences: the mutation and null behavior are front-loaded, followed by the version/conflict guidance. Every clause carries operational meaning.

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

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

For a destructive mutation tool with no output schema, the description covers the critical semantics: single-member scope, null removal, optimistic concurrency, and conflict recovery. It could mention permission requirements or irreversibility more explicitly, but it is sufficient to call the tool correctly given the 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 80%, so most parameters are already documented. The description still adds value by explaining that roleSlug null removes the grant and by reinforcing where expectedVersion must come from, though it does not document every field in 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?

States a specific mutation: "Change ONE member's workspace role," and clarifies the null-roleSlug behavior. This distinguishes it from sibling operations like company_offboard_member, company_invite_member, and listing tools, so an agent can select it without opening the schema.

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

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

Gives clear operational guidance: use the current membership version and available actions from the team or workspace-members view, and refresh after a conflict. It does not explicitly name alternatives for adding or removing members, but the prerequisites and conflict-retry path are clearly stated.

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

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

Goes well beyond destructiveHint/idempotentHint by disclosing the resulting state ('The previous Owner becomes Admin') and what does NOT change (resource and billing IDs), plus lost-response retry guidance. These are exactly the consequences an agent needs before making an irreversible ownership change.

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 action, then the gate, then the side effect, then the retry rule. Every clause carries operational information with no restatement of the title.

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

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

Strong coverage of authorization, side effects, and retry behavior for a destructive five-parameter mutation. Gaps: 'eligible' is left undefined (what roles/conditions qualify a member), the 'reason' field is unexplained, and there is no output schema, so the caller does not know what a success response confirms.

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 80% and already documents accountId, newOwnerMembershipId, idempotencyKey, and expectedCommandVersion in detail. The description only reinforces the idempotencyKey retry rule and says nothing about 'reason' or the eligibility criteria for the new owner, so it adds little beyond the schema 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?

States a specific verb and resource ('Transfer Account ownership') plus the target constraint ('an eligible existing member'), which is enough to separate it from sibling reads like company_get_ownership and from member-management tools like company_offboard_member. No ambiguity about what changes.

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

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

Explicitly names the prerequisite call ('first read company_get_ownership'), the authorization gate ('Owner only'), and the required human step ('obtain explicit confirmation'). An agent has a concrete pre-flight sequence rather than an 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 flag destructiveHint/idempotentHint; the description goes further by disclosing the actual consequence (reverts to draft rather than deleting), a precondition gate ('when its current state permits'), and the exact retry contract with idempotencyKey. That is meaningful behavior an agent could not infer from the structured fields alone.

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 ordered as consequence, verification, then failure handling — front-loaded with no filler. Each sentence carries distinct operational 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 3-param mutation with no output schema, it covers outcome, sequencing, and retry adequately. The main remaining gap is that 'when its current state permits' never says which states permit it, leaving the agent to guess whether the call will fail.

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 every parameter is documented in-schema, including the idempotencyKey retry rule. The description's sentence about retrying the identical body and key largely restates the schema text rather than adding new meaning, so 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 ('Cancel ... schedule') plus the concrete outcome ('return it to draft'), which distinguishes it from company_delete_post and company_reschedule_post by implication. It never names a sibling explicitly, so the differentiation must be inferred rather than read.

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 post-call verification step ('verify with company_get_post') and an explicit retry protocol for lost responses, which is real operational context. It stops short of naming alternatives (reschedule vs. delete vs. cancel-approval) or stating when not to use it.

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

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

Annotations already flag mutation, destructiveness and idempotency, and the description adds genuinely useful behavioral context: approval invalidation, platform-specific length checks, skipped unsupported targets, field omissions for status/scheduledTime/mediaUrls, and safe idempotent retry. There is no contradiction with the annotations.

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

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

The description is dense but front-loaded: it starts with the core action and ordering constraint, then covers special cases and retry behavior. A few sentences duplicate schema-level details, but nearly all content is useful for correct invocation.

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

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

For a complex mutation with nested platform settings and no output schema, the definition covers prerequisites, side effects, workflow ordering, verification via company_get_post, media upload alternatives, and idempotent retry. An agent has enough context to call it correctly.

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

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

Schema coverage is already 75% and the nested schema carries substantial field documentation, but the description adds operational meaning: copy channel keys from company_list_channels, empty platforms allows a channel-less draft, firstComment accepts only one object and null clears it, and retries must reuse idempotencyKey. It does not exhaustively explain every nested platform setting, so 4 is appropriate.

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

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

States a specific verb and resource ('Update an existing Agency draft') and immediately distinguishes it from adjacent workflows by naming company_schedule_post, company_get_post, company_reserve_media and company_complete_media. An agent can identify exactly which operation this is without opening the schema.

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

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

Explicitly says to save edits before media, client review or scheduling, notes that changed text/channels/settings invalidate approval, explains the empty-platforms case, and directs scheduling/media operations to the appropriate sibling tools. It also gives retry guidance for a lost response. This is close to ideal when-to-use/when-not-to-use guidance.

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

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

Annotations already flag destructive/openWorld/idempotent, but the description adds real operational context beyond them: the permission required, the fact that activating a subscription causes future events to be sent externally, that no test event is dispatched, and the exact recovery procedure (retry the identical body and idempotencyKey). That is substantive disclosure for a destructive mutation.

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 target, then the permission prerequisite, then side effects and the retry rule. No filler; the only near-redundancy is the retry guidance that also appears in the idempotencyKey schema description, but it is short and reinforces a destructive-operation safety rule.

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, open-world mutation with no output schema, the description covers permissions, external side effects, exclusions and retry safety. The notable gap is partial-update behavior: whether fields omitted from 'changes' remain unchanged or are reset, which matters given additionalProperties=false and a nested object.

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 75%, so the baseline is 3, and the description earns above that by naming the mutable fields inside the nested changes object and qualifying the URL as an 'approved receiver URL' — meaning beyond the bare ^https?:\/\/ pattern. It does not clarify update/merge semantics (whether omitted fields in changes are left untouched), which is the main remaining ambiguity.

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 (change) and resource (a Workspace webhook) plus the exact updatable fields: name, approved receiver URL, publishing events, active state. It implicitly separates itself from siblings like company_create_webhook and company_delete_webhook by being a mutation of an existing webhook, and from company_regenerate_webhook_secret by explicitly saying it cannot set the signing secret, but no sibling is named for routing.

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 (requires settings permission) and signals what this tool is not for (no test event sent, signing secret not settable). It stops short of explicitly naming the alternative tools to use for those excluded actions, so the agent must infer that secret rotation belongs to company_regenerate_webhook_secret.

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

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

Annotations cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true), and the description adds critical operational behavior: what the server does (probes bytes, marks ready), retry semantics using the SAME mediaId, retryAfterSec, and the nextAction field. This is exactly the kind of context annotations cannot 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?

Information-dense with several clauses, but each sentence is actionable: finalization, parameter source, error handling, and workflow routing. The error-code details are front-loaded after the core purpose; a slightly tighter structure could group the retry states, but nothing is wasted.

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

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

For a single-parameter finalize tool with an output-less response and rich annotations, the description covers purpose, retry semantics, error states, workflow sequencing, and exclusions. An agent has everything needed to invoke and recover 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% and the single mediaId parameter is fully documented in the schema. The description reinforces its provenance ('from get_upload_url') but adds no syntax or format detail beyond 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 (finalize) and resource (uploaded media file) and clarifies the exact precondition (after HTTP PUT to uploadUrl). It is clearly distinguishable from siblings like get_upload_url and attach_media.

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 ('Use the mediaId from get_upload_url'), state-specific routing for error codes (MEDIA_UPLOAD_PENDING, MEDIA_VALIDATION_PENDING, retryable=true), and an exclusion ('Not needed for mediaUrls attachments'). It routes the agent to get_post and update_post at the right step.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description still adds real behavioral context the annotations cannot: publishNow consumes monthly publication quota but no deferred queue slot, scheduling is asynchronous and must be inspected via get_post, and media is downloaded and validated server-side. It does not, however, disclose approval/workspace-permission requirements or rate limits, so it sits above baseline but not at the top.

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 core capability and mode selection are front-loaded in the first sentence, and the subsequent sentences are dense with actionable rules rather than filler. It is nonetheless a long single block that re-explains media handling details already present in the schema, so a little trimming would improve it.

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

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

For a 9-parameter, nested-object, mutation tool with no output schema, the description covers mode selection, quota implications, media prerequisites per platform, idempotency-adjacent retry behavior (via schema), and where to verify results (get_post). Nothing an agent needs in order 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 description coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema states only per-field: omit scheduledTime to draft, publishNow plus a future scheduledTime is rejected, and media-requiring platforms need mediaUrls in the same call. Some of this restates schema text (server-side media download, direct-URL requirement), which keeps it below 5.

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

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

Opens with a specific verb+resource and enumerates the three modes (draft, schedule, publish now) with the exact parameter that selects the third. It also names the sibling tools involved in adjacent workflows (account_context, attach_media, get_upload_url, complete_media, get_post, update_post), so an agent can place it among its siblings without another lookup.

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?

Explicit when-to-use rules are given for each mode: omit scheduledTime for a draft, set publishNow=true to publish, call account_context before batches to check plan/quota/maxScheduledDate. It also names the preferred path (mediaUrls in one call) versus the manual path (get_upload_url + PUT + complete_media + update_post) and the ChatGPT-file case, which is exactly the alternative-routing guidance this dimension rewards.

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

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

Adds real behavior beyond annotations: deleting media from a scheduled post demotes it to draft, and the prerequisite workflow with get_post/update_post. Annotations already cover destructiveness and idempotency, so this supplementary workflow context is valuable though it doesn't mention auth or irreversibility.

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 core action and error triggers, then the id source, then the side effect and recovery. 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?

Covers purpose, error triggers, id discovery, and the crucial scheduled-post-demotion consequence for a destructive mutation tool. No output schema exists, and behavioral gaps are minimal given the annotations; a slightly fuller note on irreversibility would complete it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds actionable meaning by telling the agent where to source the mediaId (get_post's 'media' array, showing per-file status), which goes beyond the schema's own note.

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 (Remove) and resource (one media file from a post group), and distinguishes itself from siblings like delete_post, prune_media_reference, and complete_media by scoping to a single media file within a post group.

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

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

Explicitly states when to use it (duplicate or never-uploaded slots blocking scheduling with MEDIA_COUNT_EXCEEDED or media-not-ready errors), how to find the required id (via get_post's 'media' array), and the downstream consequence plus follow-up (re-schedule with update_post after demotion to draft).

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

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

Goes well beyond the annotations: it enumerates exactly what is destroyed (platform-specific records and media), discloses the 409 protection conditions for published/uncertain/in-flight content, and draws the boundary that posts are not removed from social networks. That is meaningful operational context that destructiveHint/idempotentHint alone do not convey.

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

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

Three tight sentences, front-loading the action and scope, then the failure conditions, then the scope boundary. No filler and 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?

For a single-parameter destructive tool with no output schema, the description covers the action, its cascade effects, its failure mode, and its limits. Nothing an agent needs to invoke it correctly is missing.

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

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

There is only one parameter (postGroupId) and schema description coverage is 100%, so the schema already carries the parameter semantics. The description adds no format, ID-source, or lookup guidance beyond what the schema provides — 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 precise verb (delete) and a precisely-scoped resource (an unpublished post group plus its platform-specific records and media), which cleanly separates it from siblings like delete_media or update_post. The scope qualifier 'unpublished' is stated up front rather than buried.

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 when-not: published, partially published, uncertain publish outcomes, and in-progress publishing are protected and return HTTP 409, so the agent knows when this call will fail. It does not, however, name an alternative tool for handling published content, so the routing guidance is incomplete.

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?

Far exceeds annotations (which only state read-only). Discloses rich behavioral signals: the pending/outcomeUnknown safety rule, partial-publication handling, the shape of error objects, and the legacy-mirroring behavior. This is exactly the context annotations don't 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?

Information-dense and front-loaded with the retrieve scope, but it's a dense run-on of nested field inventories and procedural warnings that could be structurally separated. It earns its content but is harder to scan than ideal.

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-param, no-output-schema retrieval tool, it fully covers the returned structure, status semantics, and safety procedures. An agent has enough to call it and act on results safely.

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 (postGroupId) and schema coverage is 100%, so baseline is 4. The description explains that this ID scopes the entire group retrieve, adding light conceptual context.

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?

Precise verb+resource: retrieves a post group's details, media inventory, and platform-specific posts. It clearly delineates a read/inspection tool distinct from mutation siblings like update_post, delete_post, and company_post_action.

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?

Strong guidance on what to do after retrieval—never recreate or resubmit after partial publication, check the live account after an unknown outcome. It describes safe post-retrieval behavior but doesn't explicitly contrast with siblings like list_posts vs company_posts.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, but the description adds substantial context beyond them: this reserves a slot without uploading bytes, identical postGroupId/fileName/contentType/type reissues the URL with the same mediaId, error handling guidance ('do not infer abandonment from an upload error'), and the required Content-Type match on the subsequent PUT.

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 purpose and the crucial 'reserves a slot but does not upload bytes' caveat, then sequences the instructions with a clear 'Next:' marker. It is dense and long, but nearly every clause carries actionable workflow or safety 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 still names the returned artifacts (uploadUrl and mediaId) and describes the full downstream sequence. For a multi-step upload tool this leaves an agent with everything needed to invoke it correctly and safely.

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 baseline is 3. The description goes further by explaining how parameters interact (identical postGroupId/fileName/contentType/type reissue the URL) and by advising unique fileNames per file, which adds genuine semantics about the identity of an upload reservation.

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 a presigned S3 URL to upload a LOCAL media file (image/video) for a post.' It immediately distinguishes itself from siblings like attach_media, complete_media, and company_media, and clarifies that it only reserves a slot rather than uploading bytes.

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 covers when to call it (once per file, unique fileNames), the alternative paths (public HTTPS mediaUrls URL or upload via Publora when PUT/bytes are unavailable), and the full workflow sequence with complete_media and get_post. It even details when to use delete_media to remove a specific unfinished reservation.

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 (which only declare non-read-only, non-idempotent, non-destructive, open-world). It discloses exact daily budgets per plan tier, that budgets are shared across connections/API/MCP and automatic first comments, reset timing, exemptions for agency/company users, that attempts count even on failure, and that the backend response is authoritative. This is rich, decision-relevant behavioral context.

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

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

The description is dominated by a lengthy rate-limit and budget block placed ahead of the actual purpose, which only appears in the third sentence. Much of the limit text reads as reusable boilerplate. The essential action and its constraints are not front-loaded, so structure actively impedes quick scanning.

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 mutation tool with 5 params, no output schema, and full annotation coverage, the description supplies strong error-handling and rate-limit context. It notes the backend response is authoritative, partially compensating for the absent output schema. A brief note on the successful response shape would close the 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% and the schema descriptions are unusually detailed (mention syntax, URN formats, image constraints). The description adds little parameter meaning beyond restating that one image/GIF may be attached. Baseline 3 is appropriate when the schema does the heavy lifting.

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 a specific verb and resource: 'Post a comment on a LinkedIn post, optionally with one image or animated GIF.' This distinguishes it from siblings like linkedin_create_reaction and linkedin_create_reshare. However, this core sentence is buried behind a long rate-limit preamble, weakening immediate clarity.

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

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

It gives explicit operational conditions: LINKEDIN_DAILY_LIMIT_REACHED means wait until retryAt before retrying, never loop immediately, and LINKEDIN_COMMENTS_RESTRICTED is terminal for the target and must not be retried. It also states not to self-throttle. It lacks any comparison to sibling tools (e.g., when to use parentComment for replies vs. a top-level comment), so guidance is strong but not fully 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 declare non-destructive, idempotent, open-world behavior, and the description adds substantial context beyond that: quota budgets per tier, exemption rules, that failed attempts still consume budget, and the LINKEDIN_DAILY_LIMIT_REACHED signal with retryAt semantics. This is a genuinely useful disclosure for a rate-limited mutation tool, though it says nothing about auth requirements or what a successful response 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?

The purpose is correctly front-loaded in the first sentence, but the remaining text is a dense block of quota tiers, exemptions, and reset timing that reads more like internal policy documentation than a tool description. Every sentence is arguably operationally relevant, but the budget enumeration is heavy and could be compressed without losing agent-relevant meaning.

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

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

With no output schema, the description must carry return/error behavior, and it does cover the key failure mode and the authoritative-backend principle. For a 3-parameter, fully-schema-documented tool with annotations covering the safety profile, the description is complete enough, missing only success-response and auth detail.

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?