posterly

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

Goes well beyond the annotations by disclosing the required auth and scopes (accounts:read + posts:read), that the first answer never opens a human ticket, and the exact gated path to escalation. This resolves the ambiguity of readOnlyHint=false and destructiveHint=false by explaining precisely when a side effect can occur.

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 but front-loaded sentences: purpose first, then auth/scopes, then the escalation contract. No filler, though the escalation sentence is long and packs several conditions into one clause-heavy run.

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

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

For an 8-parameter, multi-turn tool with no output schema, the description covers the important non-obvious behavior (auth, two-step escalation gating). It omits any hint of what the first answer returns or how diagnostics surface, but that gap is minor given the absence of an output schema.

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 88%, so the baseline is 3, but the description adds cross-parameter semantics: that request_human and confirm_escalation only take effect together with a continued conversation (conversation_id) and a prior assistant answer. That relational meaning is not captured by the per-field schema descriptions.

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

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

States a specific verb ('Ask') and resource ('posterly Support AI'), plus the scope ('for the caller workspace') and the inputs it draws on (docs plus read-only account/post diagnostics). No sibling tool offers support-AI Q&A, so it is trivially distinguishable from list_conversations, manage_conversation, and submit_agent_feedback.

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?

Clearly explains the conditions that select ticket creation (continued conversation with a prior assistant answer, request_human=true, confirm_escalation=true, and explicit user confirmation). It stops short of naming alternative tools or stating when NOT to use this at all, so it is clear context without explicit 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 declare readOnlyHint/openWorldHint/idempotentHint, so the safety profile is covered. The description adds real value beyond them: 'live' signals a remote call to Google rather than cached data, and the explicit scoring rule (no service areas, or an area >80 straight-line miles, caps the score) is behavioral context an agent cannot get 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?

Three sentences, front-loaded with the action, then the return contents, then the scoring caveat. No filler, though the long enumerated section list is dense and could be tightened.

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

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

For a read-only audit with no output schema, the description adequately previews the return payload (overall score, grade, section scores, recommendations). Minor gap: all three parameters are optional, so it never clarifies how the tool resolves the target location when e.g. only workspace_id is supplied.

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 mentions no parameters at all — it does not reinforce the important account_id-vs-location_id guidance (including the warning against the ChIJ Place ID) that the schema text carries. With the schema doing the heavy lifting, baseline 3 applies, but the description contributes nothing here.

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 — 'run a live local-profile audit' for a 'connected Google Business Profile location' — and enumerates the exact outputs (0-100 score, letter grade, per-section scores, recommendations). This clearly separates it from the sibling list_/manage_google_business_* tools, which read or mutate resources rather than compute a scored audit.

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 phrase 'for a connected Google Business Profile location' implies the prerequisite (an already-connected account) but never states when to pick this over list_google_business_locations or manage_google_business_location, nor when not to run it. Usage must be inferred rather than read.

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 behavior beyond the annotations: discloses the required billing:write scope, the default period-end semantics for active/trialing plans, and the important edge case that past_due/unpaid plans end immediately regardless of immediate=false (unpaid renewal dropped, retries stop). This is exactly the kind of consequence detail an agent cannot infer from destructiveHint 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?

Front-loaded with the action and the DESTRUCTIVE/scope warning, then the required workflow, then the edge-case semantics. It is fairly long but nearly every sentence carries distinct operational information; minor tightening is possible but nothing 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 destructive mutation with no output schema, the description covers permissions, prerequisites, default vs immediate behavior, and the anomalous past_due/unpaid path. An agent has everything needed to call it correctly and warn the user appropriately.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains that reason must be captured from the user, that immediate is ignored for past_due/unpaid, and that confirm gates the call. It exceeds the schema rather than restating it.

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: 'Cancel the authenticated user's posterly subscription.' An agent immediately understands the scope, and it is clearly differentiable from pause_subscription and downgrade_subscription by the plain 'cancel' semantics.

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?

Extensive when/when-not guidance: ask the reason FIRST, only pass immediate=true when the user explicitly wants an active plan cancelled now, only call after explicit confirmation. It does not name sibling alternatives (pause_subscription, downgrade_subscription) as substitutes, so it falls just short of a 5.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true), and the description adds meaningful context beyond them: the credential-passthrough warning, the preference for scoped secrets over primary passwords, and the fact that connect_session_id lets the caller mark a session connected or failed. This is substantive behavioral disclosure.

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

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

Front-loaded with the core action, then the prerequisite, then the credential guidance, then the security warning. Dense but nearly every clause carries actionable information; the two inline lists add length without much redundancy.

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

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

For a 14-parameter mutation tool with no output schema, the description covers when to use it, prerequisites, credential selection, and the security implication. It does not say what a successful connect returns (e.g. the resulting account record), which is the only 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 100%, so the per-field documentation is already carried by the schema and the baseline would be 3. The description goes one step further by ranking credential options (prefer app passwords, bot tokens, webhook URLs, API tokens over primary passwords), which is preference meaning the schema does not encode.

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 ('Connect a credential-based social account') plus the explicit scope qualifier 'directly, without a browser session', and enumerates the supported platforms. An agent can distinguish it from create_connect_session and disconnect_account 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?

Gives an explicit prerequisite ('Call list_platforms with view=connect_link first to discover the exact credential fields'), names the alternative tool for OAuth platforms (create_connect_session), and explains which credential type to prefer per platform. Both the when-to-use and when-not-to-use cases are covered.

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 (readOnly=false, destructive=false, idempotent=false), which only flag this as a non-destructive write. The description adds that it is a SECRET-CREATING write requiring confirmation, that scopes can only be inherited from the calling dashboard key, that team-management and client-portal permissions are never copied, and that brand-limited keys cannot create keys — these are non-obvious authorization and inheritance rules an agent could not infer.

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 action and the safety warning before the permission detail, and every sentence carries a real constraint. Some sentences (the scopes/team-management sentence) are dense enough that a reader has to parse carefully, which keeps it just under top marks.

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

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

There is no output schema, and the description implies rather than states that the response contains the secret key material and whether it is shown only once. Otherwise the authorization model, scope inheritance, and confirmation requirement are covered thoroughly for a six-parameter 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 description coverage is 100%, so every parameter already has documented semantics including the scopes enum items and the confirm constant. The prose restates the workspace_client_id brand-limiting rule and the scope-inheritance rule rather than adding new detail, so the schema 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 ("Create a new posterly API key for the authenticated user") and immediately scopes who can do it (OAuth and managed assistant tokens cannot mint keys), which separates it from sibling credential tools like delete_api_key or manage_oauth_client. It stops short of naming a sibling as an alternative, so it lands at 4 rather than 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?

Explicit gate: "only use after explicit user confirmation," which the schema's confirm constant reinforces. It also tells the agent when to omit workspace_client_id (workspace-wide key) and states a precondition that a brand-limited key cannot create keys. No named alternative tool, but the when-to-use conditions are 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 declare openWorldHint=true, non-idempotent, non-destructive, but reveal nothing about the interaction model. The description adds genuinely useful behavior: the session is short-lived, it is a user-facing dashboard handoff consumed via a URL, and progress must be observed by polling rather than by a direct result. It still omits session expiry timing and failure behavior.

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

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

Two sentences, both of which earn their place: the first states what is created, the second states the required follow-up flow. The handoff mechanism is front-loaded 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 usefully compensates by naming the connect_url field the agent must surface to the user and the polling tool for progress. Annotations cover the safety profile and the schema covers all params, so the only unaddressed item is session lifetime/failure handling, a minor 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%, so the platform enum, auto_start default, and workspace_id scoping are all already documented in the schema. The description mentions connect_session.connect_url, which is a response field rather than an input, so it adds no parameter meaning beyond the structured data. 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 and resource ("Create a short-lived dashboard handoff session") and scopes it to connecting a social account, which is distinct from the plain connect_account sibling. It never explicitly names connect_account or explains why an agent would pick this session handoff instead, so it stops short of full sibling 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?

It gives actionable workflow guidance: open connect_session.connect_url for the user, then poll list_accounts with view=connect_session. That tells the agent exactly what to do after the call, but it offers no explicit when-not condition (e.g. when to use connect_account directly instead).

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 it is a non-readonly, non-idempotent, open-world write. The description adds substantial context beyond that: the return format (drop_url with token template), the no-login auth model, file/count/size limits, accepted and rejected formats, and the required follow-up call. It does not contradict any annotation.

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 purpose, then return value, workflow, constraints, and exclusions in a tight sequence; every sentence carries information. It is dense, but nothing is padding, so it sits just below the ideal for readability.

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

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

With no output schema, the description correctly explains the return value (drop_url format) and the full end-to-end flow including the subsequent list_media call. An agent has everything needed to invoke and follow through.

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%, with filename and workspace_id already documented. The description compensates for the undocumented max_files by stating the 'up to 20 per link' limit, aligning with the schema's 1-20 bounds, but adds no further syntax or per-param 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 verb and resource ('Create a human drop page') and immediately clarifies the audience and mechanism ('so ChatGPT or Claude users can upload laptop files ... without dashboard login'). It distinguishes itself from siblings by name ('not create_signed_upload', 'not the chat paperclip'), so the agent can route correctly without opening other schemas.

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

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

Explicitly prescribes the workflow: create the drop, send the URL to the user, wait, then call list_media. It also names the alternatives it is not (chat paperclip, create_signed_upload), giving clear 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 say readOnly=false and destructive=false; the description adds substantial behavioral context: third-party media URLs are copied into posterly storage and short-lived signed URLs must still be live at run time, a repeat idempotency_key within 10 minutes returns the original post with deduplicated: true, and TikTok defaults to public/auto when privacy_level is omitted. Minor tension: calling it a 'DESTRUCTIVE WRITE' reads harsher than destructiveHint=false, though it is consistent with a non-read-only mutation, and it usefully warns the agent to confirm first.

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 confirmation requirement are front-loaded, and nearly every sentence encodes a genuine constraint (media URL liveness, Instagram native tags, retry dedup, TikTok defaults). It is a dense single block though, and the Instagram-specific rules could be segmented for faster 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 an 18-platform tool with 16 parameters, deeply nested settings objects, no output schema, and per-platform quirks, the description covers the dangerous-operation warning, confirmation precondition, platform-specific gotchas, error/retry behavior, and where to get further schema detail. An agent has enough to call this correctly.

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

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

Schema coverage is 94%, so baseline is 3, but the description adds real meaning beyond the schema: it distinguishes Instagram caption @mentions from native user_tags and collaborators, explains when caption_addon features are allowed (Facebook Login account, caption, feed photo/Reel/carousel, not Stories), and clarifies that confirm must follow explicit user confirmation. These are cross-parameter constraints 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?

Opens with a specific verb+resource+scope: 'Schedule or immediately publish one social media post.' The 'one' explicitly separates it from the sibling create_posts_batch, which is also named later, so the agent can distinguish the two 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 explicit when-to-use routing (single post here, create_posts_batch for multiple), a precondition ('Always confirm caption + scheduled_at + account_id/workspace with the user before calling'), a prerequisite lookup step (list_platforms with view=schema and account_id for Instagram native features), and retry guidance with idempotency_key. Exclusions for Stories and poll+comment-prompt combinations are stated outright.

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 contains useful behavioral detail: confirmation requirements, media copying, partial success with failed indices, and retry deduplication. But it directly contradicts the annotations by calling this a 'DESTRUCTIVE WRITE' while destructiveHint is false, and by describing idempotent retry behavior while idempotentHint is false. That is an annotation contradiction.

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

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

The description is dense but front-loaded: scope first, then the destructive/confirmation warning, then operational edge cases. Given the complexity and risk of a 25-post batch, 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 complex batch write with no output schema, it covers the critical behavior an agent needs: explicit confirmation, partial success, failed item indices, retry semantics, media copying, and TikTok defaults. The main gap is that it does not explicitly route the agent to single-post or validation alternatives.

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%, so the description should add meaning. It does so for confirm (explicit user confirmation for the whole batch) and idempotency_key (reuse on lost response, 10-minute dedupe), and it frames what must be shown per post before calling. It does not explain the full posts schema, but the schema itself carries substantial per-field detail.

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

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

The description states a specific verb and resource: 'Create 1-25 scheduled or immediate social posts in one API request.' The 1-25 batch scope clearly distinguishes it from the single-post sibling create_post, even without naming that sibling.

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

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

It gives an important operational prerequisite—show every post's details and get explicit confirmation for the whole batch—and implies batch use. However, it never explicitly says when to use this tool versus create_post or validate_post, nor when a batch is inappropriate.

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 annotations: accepted formats, 50MB limit, HEIC rejection, PDF/LinkedIn document post handling, per-file failure reporting, pin_content_type locking, mandatory Content-Type header, and 15-minute slot expiry. These are exactly the operational traits an agent needs for a non-idempotent, open-world creation 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?

Front-loaded with purpose and formats, then walks through single-file, batch, upload workflow, and PDF-specific handling in a logical order. It is dense and slightly run-on, but nearly 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 complex upload tool with no output schema, it covers formats, size, batch behavior, the PUT workflow, returned headers/upload_url/public_url, and expiry. Combined with full schema coverage, an agent has enough 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 100%, so the schema already documents filename, content_type, size, files, workspace_id, and pin_content_type. The description mainly restates the single-file vs. files usage pattern and pin_content_type behavior that the schema descriptions already cover, adding little new parameter semantics.

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

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

States a specific verb and resource: 'Create signed upload URLs' for images, videos, and PDFs, with batch size and media type limits. It implies a distinction from upload_media via 'larger' files, but never names the sibling alternatives, 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?

Clear usage context: use single-file fields for one file, `files` for 1–20, and then PUT bytes and pass public_url to create_post / create_posts_batch. It does not explicitly say when to choose this over upload_media or create_media_drop, leaving the 'larger files' implication 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 declare a non-read-only, open-world, non-idempotent write; the description adds real value beyond them by flagging outbound side effects, the mandatory confirmation gate, and that the signing secret is returned only once. That is exactly the behavioral context an agent needs before invoking an externally visible write.

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 confirmation requirement is front-loaded right after the purpose statement.

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 discloses the one notable return value (the signing secret, delivered once). Combined with the confirmation protocol this is largely complete, though it omits error/failure behavior for an outbound-integration write.

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 17%, but the description compensates by naming the four fields the agent must surface for confirmation (URL, workspace, events, active state). It says nothing about the 'description' field, enum event values, or defaults, so meaning is only partly filled in.

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 a webhook subscription') and scopes it to post/account/analytics events, which is enough to separate it from list_webhooks. It does not explicitly say how it differs from the sibling manage_webhook, so the agent must infer that manage_webhook handles updates/deletes.

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 pre-call procedure: show target URL, workspace, events and active state, then obtain explicit confirmation. That is clear usage context, though it never names an alternative tool or states when not to create a webhook (e.g. when one already exists).

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, and the description builds on that with real operational context: the ownership boundary, the three categories that cannot be revoked, and the confirmation gate. The 'DESTRUCTIVE' callout with the confirmation instruction is exactly the behavioral guidance a mutation tool 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?

Three sentences, zero filler. The destructive warning and call to action are front-loaded, followed by eligibility limits, so the highest-risk information is read first.

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 destructive tool with no output schema, the description covers purpose, ownership scope, confirmation workflow, and hard exclusions; idempotency and safety profile are carried by annotations. Nothing an agent needs to call it safely 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% and both parameters are already documented, including the important distinction that key_id is the resource UUID rather than the pst_live_ secret. The description reinforces the confirmation requirement but adds no new syntax, format, or constraint information beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Revoke') plus resource ('API key') and adds scope ('owned by the authenticated user'), which cleanly separates it from create_api_key and other key-management siblings. An agent knows immediately this is key revocation, not secret rotation or general deletion.

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-not conditions: cannot revoke the key authenticating the current request, OAuth-issued keys, or managed assistant keys. It also prescribes the pre-call workflow ('show the user the exact key ID/prefix/name... and get explicit confirmation'), leaving nothing to inference about eligibility or sequencing.

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: publishing posts are never deleted, published posts go down only with delete_mode=platform plus confirm_published=true, posterly-only leaves the live post up, live deletion requires eligible platforms and permissions (threads_delete, youtube.force-ssl), and refusals keep the record. This is exactly the operational context annotations cannot 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?

Front-loaded with the destructive warning and the two deletion modes, and nearly every sentence carries operational detail. It is dense but warranted for a conditional destructive tool, with only minor room for tightening.

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 prerequisites, permission requirements, the preview/confirm workflow, per-mode behavior, and refusal handling for a destructive mutation with no output schema. 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%, so the baseline is 3, but the description adds real meaning: delete_mode=platform pairs with confirm_published, confirm requires preview_id for previewing actions, and group_id matches caller-defined group_id/post_group_id/api_group_id/release_id. It explains parameter interdependencies beyond the schema's per-field text.

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?

Starts with a specific verb+resource ('Delete posts') immediately flagged DESTRUCTIVE and IRREVERSIBLE, then splits cleanly into the post_id and group_id modes. An agent can distinguish it from get_post/update_post 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 routes usage: single post via post_id requires fetching first with get_post and confirming, bulk via group_id matches drafts/scheduled/failed/paused only, and the preview-then-confirm flow is spelled out. The prerequisite (get_post) and the alternative (group_id) are both 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 flag destructiveHint=true, but the description goes well beyond them by disclosing the concrete consequences: removal of the account connection, emission of account.disconnected webhooks, and possible transfer of Instagram scheduled posts to a replacement account. The 'IRREVERSIBLE' warning and the required confirmation gate add real behavioral context an agent cannot infer from the annotations.

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

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

Two sentences, front-loaded with the destructive/irreversible warning before the procedural instruction, with zero filler. Every clause carries actionable information (side effects, webhooks, Instagram post transfer, confirmation gate).

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 two-parameter mutation with no output schema, the description covers what the agent needs: preconditions (list_accounts, user confirmation), consequences (connection removal, webhook emission, possible post transfer), and reversibility (irreversible). Nothing material is left unspecified.

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

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

Schema description coverage is 100%, so both parameters (account_id, confirm) are already documented in the input schema, including the requirement that confirm be true only after explicit user confirmation. The description reinforces the confirmation workflow but adds no new syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb ('Disconnect') plus the exact resource ('a connected social account') and the system it lives in ('from posterly'). It is immediately distinguishable from the sibling 'connect_account' and from unrelated mutations like 'delete_post' or 'delete_api_key'.

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 prerequisites and an ordering: call list_accounts first, show the user the exact account/platform/workspace, and obtain explicit confirmation before invoking. This is a complete when/how-to-use protocol rather than a vague hint, and it names the sibling tool to consult first.

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/idempotentHint, but the description adds real value beyond them: the draft path is not scheduled and publishes nothing, a previously-converted suggestion is left untouched (no-op rather than overwrite), and a user-confirmation step is mandated. It does not describe the response payload, but that is a minor omission given the destructive/idempotent hints are already present.

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

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

Front-loaded with the primary action and its effect, then the alternate mode, then safety. Roughly three sentences with minimal redundancy, though 'A draft is not scheduled and nothing is published' partially restates the draft concept.

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 no output schema, the description covers both modes, side effects, idempotent no-op behavior, and a confirmation requirement. The only gap is what 'dismiss' does to the underlying record versus merely hiding 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 the baseline is 3; the description goes further by explaining the consequence of save_as_draft=true (unpublished draft, unscheduled, nothing published) and implying the default dismiss behavior when omitted. It adds semantic weight beyond the boolean's own text.

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 (dismiss) and resource (proactive post suggestion) with the resulting effect ('stops appearing'), then immediately clarifies the alternate mode (save_as_draft true → unpublished draft). An agent can distinguish this from create_post or list_post_suggestions without opening the schema.

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

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

Gives explicit operational context — 'WRITE: confirm the exact suggestion with the user first' — and an exclusion: it will not dismiss a suggestion that was already turned into a post. It does not explicitly name which sibling to use to obtain the suggestion ID or to create a real post instead, so it stops short of full alternative routing.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds substantial context beyond them: timing of the new limits/credits (immediate), timing of the price change (next renewal), the no-refund policy for the current period, and the required billing:write scope. This is exactly the behavioral detail an agent needs before 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?

Front-loads the action, then packs the billing consequences, direction constraint, permission requirement, and confirmation gate into tight clauses. No filler; every sentence carries information an agent must act on.

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 fully covers the preconditions, side effects, and billing timing an agent needs to call a destructive mutation safely. Nothing material 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 both parameters are already documented, and the description largely restates the tier semantics. It does add a meaningful constraint beyond the schema ('explicit lower tier' — the target must be downward), but it does not enrich the 'confirm' flag beyond what the schema already 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+resource (move the subscription down a tier) with immediate scoping of what 'down' means, clearly distinguishing it from upgrade_subscription, cancel_subscription, and pause_subscription in the sibling set. An agent knows exactly what the tool 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?

Provides clear when-to-use context ('strictly downward only', 'only call after the user explicitly confirms') and a prerequisite ('requires billing:write'). It does not explicitly name upgrade_subscription as the alternative for upward moves, relying on inference, so it falls just short of 5.

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

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

Annotations already declare a safe read-only/idempotent profile, and the description layers on genuinely non-obvious behavior: the enforced 1-hour gap between posts, preferred-hours respect, the America/New_York timezone default, and the 7-day ranking window with 1-5 stars and a per-slot reason. This is exactly the context annotations cannot 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?

Four tight sentences, front-loaded with the purpose and constraints before the strategy detail. The inline quoting of strategy "best_engagement" is slightly awkward, 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?

With no output schema, the description still tells the agent what a slot contains (UTC instant to pass as scheduled_at, star rating, reason), which is the key return-value detail. It leaves out the shape of non-ranked slots and the role of workspace_id, minor gaps for a 5-parameter read tool.

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

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

Schema coverage is 60%, and the description compensates for the uncovered gaps: it warns that timezone has a hidden America/New_York default and must be set explicitly, and that account_ids is mandatory for best_engagement. workspace_id remains unexplained in both schema and description, which keeps it from a 5.

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

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

States a specific verb + resource ('Find available time slots for posting') and immediately scopes it with the constraints that define the result (1-hour gap, preferred hours). Clearly distinguishable from creation siblings like create_post or listing siblings like list_posts.

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

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

Gives explicit operational guidance: always pass timezone explicitly (with the default named), and best_engagement requires account_ids. This selects between the two strategy modes. It does not, however, mention when to use this tool versus alternatives such as get_post or validate_post, or when scheduling is inappropriate.

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

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

Annotations only supply the safety profile (not read-only, not idempotent, non-destructive, open-world). The description adds genuinely new behavior: it consumes AI Caption Assist quota (a metered side effect consistent with readOnlyHint=false) and yields options rather than persisted artifacts. It does not disclose failure modes when quota is exhausted or whether results are cached across identical calls.

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

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

Two sentences, no filler, and the capability statement is front-loaded ahead of the boundary caveat. Every clause is load-bearing.

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

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

For a 15-parameter tool with a nested manual_brand_voice object, three enums, and no output schema, the description is far too thin. It never explains the generate-vs-adapt workflow that most parameters depend on, and gives no hint about what the returned caption options look like or how many are returned per platform.

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

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

Schema description coverage is 0% across 15 parameters, so the description carries the full burden and largely fails it. 'Generate or adapt' faintly gestures at the mode enum and 'one or more social platforms' at platforms, but the critical mode/source_caption/source_platform coupling, tone, hashtag_strategy, brand-voice object, and the preserve_* flags are entirely unexplained.

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 gives a specific verb pair and resource ('Generate or adapt AI caption suggestions') plus scope ('one or more social platforms'). The second sentence immediately demarcates it from the create_post family, so an 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?

The clause 'it does not create, draft, schedule, or publish posts' is an explicit when-not boundary that routes agents away from create_post/create_posts_batch, and 'returns options only' clarifies the output-only nature. It lacks a positive 'use this when you need copy suggestions before drafting' framing and never names the alternative tool, so it stops short of a full 5.

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

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

Annotations cover the safety profile (readOnly=false, openWorld=true, idempotent=false), and the description adds real behavioral context beyond them: the operation costs credits, is asynchronous (returns job_id), and requires explicit user confirmation. It does not restate non-idempotency or describe failure/credit-refund 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 dense sentences: what it does, how to retrieve results, and the cost/confirmation constraint. The credit warning is capitalized and front-loaded where it matters most.

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 12-parameter async mutation with no output schema, the description covers return shape (job_id), retrieval path, credit risk, and the confirmation gate. It leaves provider capability differences (e.g., xAI resolution limits) to the schema, which is reasonable but not fully self-contained.

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

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

Schema coverage is 67% and the schema itself carries rich enum and billing explanations (model, quality, resolution, thinking_level, reference URLs). The description only names the fields to confirm with the user, adding workflow meaning rather than new parameter semantics, 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 (queue an AI image job) plus the backing service and provider options (Nano Banana/Gemini, Grok Imagine/xAI), and notes the return value. An agent can immediately distinguish this from generate_video and other 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?

Explicitly prescribes the follow-up workflow (poll list_jobs with type=image to get URLs) and a hard precondition (confirm subject + style + aspect_ratio + quality + provider with the user before calling). It does not name when to prefer this over generate_video or when not to use it, so it stops short of 5.

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

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

Annotations only declare the generic write profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds information annotations cannot convey: the call consumes credits, requires explicit user confirmation of specific fields, and is asynchronous so results must be polled from list_jobs and read from final video_url.

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: identity first, the high-stakes credit/confirmation warning second, the polling instruction last. Nothing is redundant and the most important operational constraint is front-loaded rather than 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?

For a 14-parameter mutation tool with no output schema and thin schema descriptions, the description covers the queue-then-poll lifecycle and the cost gate but not the input modes implied by image_url, end_image_url, source_video_url, and reference_images. An agent would not know from the text alone whether this is text-to-video, image-to-video, or video extension.

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 21% across 14 parameters, so the description must compensate and it only partly does: it enumerates provider, prompt, duration, resolution, aspect ratio, and audio. Model, image_url, end_image_url, source_video_url, reference_images, negative_prompt, and workspace_id remain undocumented anywhere beyond their names and enums.

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 ('Queue an AI video job') and names the concrete backends (Google Veo 3.1, xAI Grok Imagine Video 1.5), so the agent knows this is asynchronous video generation. It also routes status checks to list_jobs, though it does not distinguish itself from nearby siblings like generate_image, get_video_options, or run_video_function.

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

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

Gives an explicit precondition workflow: confirm provider, prompt, duration, resolution, aspect ratio, audio, and credit cost with the user before calling, and it names the follow-up tool (list_jobs with type=video). It does not state any when-not-to-use conditions or explain when a different generation tool would be preferred.

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/non-destructive, yet the description still adds real value: it discloses the required billing:read scope, which is the most common failure mode when calling, and explains the workspace-shared wallet semantics so the agent knows the balance is not per-user. It omits any note on staleness or caching of the balance.

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 dense sentence that front-loads the verb and resource, then the returned fields, then the workspace-wallet caveat, then the scope requirement. Every clause carries distinct information with no restatement of the name.

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

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

With no output schema, the description correctly compensates by listing the five values returned. For a zero-parameter read tool this is close to complete; only the unit/expiry semantics of the different balances and any staleness behavior are left implicit.

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

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

The tool takes zero parameters, so there is nothing the description needs to disambiguate; a baseline of 4 applies. The schema is empty with additionalProperties false, matching the parameterless 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?

States a specific verb and resource ('Get the posterly AI credit balance') and enumerates exactly what the payload contains: available balance, monthly allowance left, purchased packs, plan tier, next reset. It does not explicitly distinguish itself from near siblings like get_subscription or manage_plan, 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?

No when-to-use guidance is given, no prerequisites for calling, and no naming of alternatives such as get_subscription for billing details or manage_plan for changing tiers. The clause 'this is the balance the caller can actually spend' clarifies interpretation, not invocation timing.

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 access, so the safety profile is covered. The description adds real operational context beyond that: exactly which fields come back per view and that failure reasons are surfaced when a publish failed. It omits behavior for a nonexistent post_id (error vs empty), which keeps it from 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?

It is front-loaded with the one-line purpose, then two clearly parallel clauses for the two views. The field enumerations are long but each item is informative; a slightly tighter structure (e.g., bullets or comma-grouping) would read better than the trailing 'and ... and ... and' chain.

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

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

With no output schema, the description carries the burden of describing return values, and it does so thoroughly for both views — listing returned fields for view=post and the diagnostic categories for view=missing. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description materially enriches the 'view' enum by spelling out the contents of each mode rather than restating 'post or missing.' post_id itself gets no extra explanation, but the schema is adequate there.

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 names a specific verb and resource with scope: 'One post by ID.' It then splits the tool's two modes by name (view=post, view=missing), which cleanly separates it from list_posts and from mutation siblings like update_post.

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

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

It states the default mode and explains what view=missing is for ('how to fix it before the post can publish'), giving clear context for choosing between them. It does not, however, point to validate_post or list_posts as alternatives for adjacent tasks, 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?

Annotations already carry readOnlyHint, idempotentHint and destructiveHint=false, so the description doesn't need to restate safety. It does add context the annotations can't supply: the required billing:read scope, the fact that upgrade targets, prices, limits and credits are included, and the caveat that limits stay frozen on a trial until the paid plan starts.

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 most important detail, what the tool returns, comes first, followed by when to call it, and then the trial caveat and the auth requirement. It is dense and most sentences are useful, but the long run of quoted trigger phrases makes it heavier than it strictly 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?

No output schema exists, so the description must describe what comes back; it does so field by field, including the plan-ladder and Agency extra-accounts data. It also covers the auth prerequisite and the trial edge case, leaving nothing an agent needs in order to call this zero-parameter read correctly.

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

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

The tool takes no parameters at all, so there is nothing for the description to disambiguate and the baseline is the maximum. The schema is closed (additionalProperties: false), and nothing in the description conflicts with that.

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 and enumerates exactly what the response contains: status, tier, cancel-at-period-end, period end, trial end, pause state, seats in use and the account limit. That field list separates it cleanly from near siblings such as get_credits or manage_plan, which an agent might otherwise confuse with it.

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 names the concrete user intents that select this tool ("upgrade", "change plan", "add accounts", "how many accounts") and tells the agent to call it FIRST. It also defers the trial-limit follow-up to manage_plan, so the boundary between the two tools is explicit.

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 safety bar is covered. The description adds non-obvious behavior beyond them: newest-first ordering, that the output signals whether more updates exist, and that a subscription is required.

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

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

Three tight sentences: what it returns first, then how to page/narrow, then the precondition. Zero filler and the key scoping information is front-loaded.

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

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

With no output schema, the description usefully discloses ordering, the existence of a more-results signal, and the subscription gate. It doesn't describe the fields of an individual update, but nothing needed to invoke the 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?

Schema coverage is 100%, so all four parameters are already documented (limit bounds, since ISO date, offset paging, include_content markdown body). The description restates the offset/since pagination strategy but adds no syntax or format 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 ('Get the latest posterly product updates and news from the updates feed') and enumerates the content types (features, improvements, fixes). No sibling tool overlaps this feed, so the agent can identify it immediately.

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 direction ('page with offset or narrow with since') and a prerequisite ('Requires an active posterly subscription'). It stops short of naming when-not-to-use or a competing tool, but no sibling competes for this job.

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 readOnly/idempotent/non-destructive, so the bar is lower. The description adds genuinely new behavioral context: it discloses that credit costs are merely estimated in the listing and that invoking it spends no credits, which is exactly the concern an agent would have before a paid generation flow. It does not describe pagination or response shape beyond the field list.

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

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

Two tight sentences with no filler: the first enumerates what is listed, the second removes the main misreading (that this generates or charges). Front-loaded with the verb and resource.

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, but the description compensates by naming the returned categories (input modes, durations, resolutions, aspect ratios, credit-cost estimates). With zero params and annotations covering the safety profile, 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?

The tool takes zero parameters, so per the rubric the baseline is 4. Nothing in the description is needed to explain inputs, and it correctly implies no arguments are required.

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 ("List") plus concrete resource (Google Veo / xAI Grok video generation options) and an enumeration of the option categories returned. The closing sentence explicitly separates it from the sibling generate_video, 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?

The negative clause "Does not generate video or spend credits" implicitly routes the agent to generate_video/run_video_function for actual generation and signals this is the discovery step. There is no explicit "call this before generating" instruction, but the context is clear and no alternatives are named outright.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful content-level disclosure by listing what is returned (usage, remaining posts, URL-blocking status, add-on plan), but says nothing about auth requirements, rate limits, or whether the workspace_id is optional/defaulted.

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

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

One front-loaded sentence with no filler; the verb and resource lead and the returned facets follow. The list of facets is slightly run-on but each item earns its place by signaling return content absent from an output 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?

With no output schema, the description correctly compensates by enumerating the returned fields, and the read-only annotations carry the safety profile. Given a single-parameter read tool this is nearly complete; only the optional/default nature of workspace_id and any permission requirements are unaddressed.

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

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

Schema description coverage is 0% for the single workspace_id parameter. The phrase 'for a workspace' hints at the scope but adds no format, default, or behavior detail. With only one self-explanatory parameter the gap is minor, but the description does not compensate for the missing schema documentation.

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 (Get) and a specific resource (managed X posting quota) and enumerates the facets returned: usage, remaining posts, URL-blocking status, and add-on plan info. It is distinguishable from generic siblings like get_credits or get_subscription by being X-posting-specific, though it does not explicitly name the nearest alternative.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no reference to alternatives such as get_credits or get_subscription that an agent might confuse with quota. Usage is implied by the resource name (check posting quota for a workspace) but left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds valuable behavioral details beyond annotations: it notes that learned_voice is read-only and never overwrites the brand profile, that performance_profile may return null with a reason for non-Pro plans, and that connect_session polling should stop at connected, failed, cancelled, or expired. It also mentions that connection status reasons/dates are returned but never tokens. These additions significantly enhance transparency, though rate limits or auth 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?

The description is information-dense and front-loads the overall purpose before detailing each view. Every sentence serves to explain a view's behavior or a specific constraint. It is somewhat lengthy but justified by the tool's complexity (four views, multiple parameters), though it could be structured with clearer separation (e.g., bullet points) for readability.

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

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

Given the tool's complexity (multiple views, five parameters, no output schema) and rich annotations, the description is mostly complete: it covers what each view returns (summaries, traits, stats, status polling) and includes critical usage details (read-only nature, plan requirement, polling stop conditions). It lacks minor details like pagination behavior or error handling, but these are not essential for an agent 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 description coverage is 100%, so the baseline is 3 even without additional parameter info in the description. The description does reiterate the purpose of each view and the connection filter, but it largely duplicates what the schema already provides (e.g., the schema already describes account_id's required views and workspace_id filtering). It adds marginal semantic clarity beyond the schema, such as the Instagram-specific check, but does not compensate for any schema gaps.

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

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

The description states a specific verb ('list' implied by name) and resource ('connected social accounts') and elaborates on the multiple views (accounts, learned_voice, performance_profile, connect_session) that this tool uniquely serves. It distinguishes itself from siblings like list_platforms (which likely lists available platforms, not connected accounts) through the detailed view breakdown.

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

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

The description gives clear usage context for each view and specific conditional guidance, such as 'check this before Instagram user_tags or collaborators' and 'Pass connection=needs_reconnect to list only accounts that need a reconnect.' However, it does not explicitly name alternative tools or state when to use this tool versus sibling listing tools, leaving some 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 declare readOnly, idempotent, non-destructive, closed-world reads, so the safety profile is covered. The description adds real behavioral detail beyond that: newest-first ordering, the existence of a 'more events' signal in the output, pagination mechanics, and a cap on offset+limit. It does not explain retention windows or what an empty result means, so not a 5.

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

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

Three front-loaded sentences with no filler; the enumeration of event kinds and the pagination clause both earn their place. Slightly dense in the second sentence, but appropriately sized for a feed tool.

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 correctly signals the pagination/end-of-results behavior an agent needs. It omits the meaning of the type enum and the workspace scoping filter, which for a 6-parameter tool is a modest 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 coverage is only 33%, and the description compensates by explaining offset/limit paging behavior and naming 'since' and 'post_id' as narrowing filters. The 'type' enum (all/activity/publish) and workspace_id are left unexplained, which is the remaining 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 and resource (list activity/publish events) with concrete event categories (status changes, publish attempts, failures, retries) and ordering (newest first). The phrase 'agent notifications feed' distinguishes it from sibling listers such as list_posts, list_comments, and list_jobs.

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

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

Gives clear when-to-use context ('use this as the agent notifications feed') and when NOT to conclude nothing else happened, plus two narrowing strategies. It never names an explicit alternative tool, so it falls short of a 5, but the intended usage scenario is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description still adds meaningful behavior: 'include_extras reads saved extras only and never starts a sync' (a key no-side-effect guarantee), a plan-gating requirement for insights, and 'most recent first' ordering with limit/offset. It does not discuss error behavior for missing account_id or rate limits, keeping it below the top mark.

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 platform list, then organized view-by-view so the reader can scan to the relevant section. It is dense and a bit long, but each clause carries substantive detail (metrics, filters, plan gating, no-sync note) rather than repetition.

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

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

With no output schema, the description still conveys what each view returns (metric names per platform, feedback tier/diagnosis/next action/baseline), pagination defaults, and presentation formats. A fuller account of the response envelope (e.g. summary vs snapshot shape) would be needed for a 5, but this is sufficient to call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-view applicability the schema only implies: which parameters apply to accounts, posts, and insights, that presentation is valid only for accounts/posts, and that include_extras is accounts-only. This conditional parameter routing is genuine 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?

The description names the resource (analytics for connected accounts), enumerates the platforms, and enumerates the three views with the specific metrics each returns. An agent can distinguish it from list_posts or list_comments because it explicitly frames output as snapshots, summaries, and per-post metric rollups tied to a view selector.

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 per-view routing guidance, including the non-obvious rule that Google Business per-post rows do not exist and its totals live on view=accounts, plus the Pro-plan-or-higher prerequisite for view=insights. It stops short of naming sibling tools (e.g. list_posts, list_comments) as alternatives for raw post/comment data, so exclusions are implicit rather than explicit.

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, so the safety profile is covered; the description adds the access-scoping ('brands the caller can access'), the legacy-brand-group linkage, and per-view content. It does not mention pagination, result limits, or ordering for large brand lists, which is the remaining 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?

The default view and its output fields are front-loaded, followed by one clause per remaining view — no filler sentences. It is a single dense paragraph, which is harder to scan than a bulleted listing but is appropriately sized for a four-mode dispatcher.

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 return-value explanation and does so for every view, including the profile's visual-identity fields. Missing only operational details an agent might want: pagination/limits and behavior when brand_id is invalid or inaccessible.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by mapping each enum value to the exact payload it returns and specifying which views require brand_id, and it clarifies that omitting workspace_id spans every accessible workspace. This is meaningfully more than the terse schema descriptions.

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

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

Opens with a specific verb+resource ('Brands (clients) and their saved context') and then enumerates all four view modes with what each returns (brand list with IDs/workspace/source/account count; single brand with legacy group; assigned social accounts; voice-and-tone profile with visual identity). It explicitly carves out the boundary against the sibling list_accounts by saying view=accounts is 'use when the user names a brand, not a handle'.

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?

States the default (view=brands), the required parameter for each non-default view, and an explicit selection rule versus the handle-based alternative. An agent can choose the correct mode and parameters without opening the schema.

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 crucial behavioral constraints far beyond the schema and annotations. It details specific operational requirements, such as needing 'Pro plan or higher' and the 'posts:read' permission. It also manages user expectations by stating the current lack of support for certain platforms and its future development status.

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 highly dense, trying to cover platform scope, operational modes, and support limitations all in one paragraph. While the information is vital, it is not optimally structured or concise, leading to slight clutter.

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

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

The tool definition is extremely comprehensive. It provides all necessary context for an agent to determine platform compatibility, necessary permissions, functional mode (search vs. fetch), and hard limitations (unsupported platforms), making it contextually complete for its complexity.

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

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

Although schema coverage is high (90%), the description provides valuable context that the schema lacks. It clarifies that the tool's functionality changes drastically depending on whether comment_id is used, and it clarifies the scoping of workspace_id (i.e., omitting it searches all workspaces).

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 defines the tool's purpose as listing 'Social inbox comments and replies' across specific platforms like Instagram, Facebook, Threads, and LinkedIn. It also distinguishes between two core behaviors: bulk filtering without a comment_id, and retrieving a specific comment and its replies when comment_id is provided.

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

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

It provides explicit usage guidelines by defining the operational modes based on the presence of the comment_id parameter. Furthermore, it provides strong negative usage constraints, specifically stating that YouTube and TikTok are refused by this tool rather than returning an empty list, helping the agent decide when the tool is inapplicable.

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), and the description adds substantial context on top: the required plan and posts:read scope, mode-dependent limit semantics with default 50 and max 100, and the Meta reply-window model including the caveats that a reply does not extend the window and the window is not inferred from loaded messages. Those domain constraints are exactly the kind of thing an agent cannot get 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?

Purpose is front-loaded in the first sentence, followed by the two-mode branch and then the reply-window nuance — a logical order. Four dense sentences with no filler, though the reply-window paragraph is long enough that it could be trimmed 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 10-parameter read tool with no output schema, the description covers the critical gaps: mode branching, pagination semantics per mode, auth/plan requirements, and one important returned field (reply window). It doesn't describe the shape of returned conversation objects beyond that, and pagination metadata (totals/has_more) is unmentioned, but the essentials for correct invocation are 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 coverage is 100%, so the per-parameter baseline is 3; the description earns above that by explaining that limit/offset mean rows in list mode but message count in single-conversation mode, and that filters only apply when conversation_id is absent. It also reinforces the Threads exclusion for platform. The remaining filter interplay (e.g., that 'all' excludes archived) is left to the schema.

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

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

The description names a specific verb and resource ('Social inbox DM conversations for Instagram and Facebook Page inboxes') and immediately splits the tool's two operating modes by presence of conversation_id. It also scopes out a false friend ('Threads has no DMs'), so an agent can distinguish it from comment-related siblings like list_comments.

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

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

Clear conditional usage is spelled out: omit conversation_id to list with filters, include it to fetch one thread and its messages, and only workspace_id may be combined in that mode. It also states the plan and scope prerequisite ('Pro plan or higher plus posts:read'). It stops short of naming manage_conversation as the tool to use for replying or mutating a thread, though the reply-window sentence implies 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?

Beyond annotations, the description discloses that the tool is disabled until location edits are enabled, does not call Google while off, and omits business name/address/phone/website from results. These are meaningful behavioral and output-scope details not captured by readOnly/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 short sentences with the purpose front-loaded and no filler. There is minor redundancy between 'Stays off until location edits are switched on' and 'does not call Google while it is off,' but overall it is efficient.

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

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

It covers the prerequisite and excluded output fields, which helps for a read-only tool with no output schema. However, it does not explain what 'attributes' or opening-hours results look like, and it leaves the single-location vs list ambiguity unresolved.

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

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

Schema description coverage is 100%, so parameter documentation is already complete. The description only repeats 'Pass account_id or location_id' and does not add format, precedence, or behavioral 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 states a specific action (read opening hours and attributes) and resource (Google Business location), but it says 'for one Google Business location' while the tool name/list semantics suggest listing locations. This mismatch leaves the core purpose somewhat ambiguous and does not distinguish it from siblings like list_accounts or manage_google_business_location.

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 useful prerequisite ('Stays off until location edits are switched on') and suggests passing account_id or location_id, but it does not say when to use this tool instead of alternatives such as list_accounts or manage_google_business_location, nor what to do when the feature is off.

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 read-only, idempotent, open-world behavior. The description adds useful context about return fields and pagination behavior over an already-fetched gallery, without contradicting 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 dense sentences, front-loaded with purpose, then scope and pagination. Every sentence contributes useful 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?

No output schema exists, but the description lists the returned fields and explains pagination and scope. It is nearly complete for a read-only listing tool, though it could mention permission requirements or error behavior.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning by clarifying that omitting location/account scope lists every accessible GBP location and by summarizing pagination defaults.

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: listing photos and videos in a Google Business Profile gallery. It also distinguishes this gallery media from media attached to a post, though it does not explicitly differentiate itself from the manage_google_business_media sibling.

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

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

Explains that it can target one location/account or every accessible GBP location, and notes that this is separate from post media. It lacks explicit when-not guidance or direct alternatives for the management sibling.

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

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

Annotations already cover read-only, idempotent, open-world and non-destructive behavior, so the bar is lower. The description still adds real context: it pages through all reviews rather than the first 50, returns full untruncated text plus dates and per-location totals, and flags the Place ID as output-only. It stops short of describing permission requirements or rate limits.

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

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

Two dense sentences, front-loaded with the resource and the default view, then the alternate view and its output-only caveat. Every clause carries information an agent needs, 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?

Given eight parameters, two views, no output schema and read-only annotations, the description covers the return contents, paging strategy, filtering, the review_name handoff and the Place ID trap. An agent has what it needs to call this correctly without guessing.

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

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

With 88% schema coverage the schema already documents most parameters, but the description adds useful semantics: rating and unanswered are filters on the reviews view, limit/offset page through large result sets, and review_name is the handle for the reply/delete tool. That goes beyond restating 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 names a specific resource (Google Business Profile reviews) and clearly splits it into two behaviors, view=reviews and view=review_link, so an agent can tell them apart immediately. It also names the sibling manage_google_business_review as the mutation path.

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 routing rules: default view=reviews for listing with filtering and paging, view=review_link when an account_id or location_id is supplied to get the public review link and Place ID. It also states the exclusion that the ChIJ Place ID must NOT be fed back as location_id, and points reply/delete to manage_google_business_review.

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 the annotations: the 20-item cap, the warning that place IDs from view=places are regions and not the review-link Place ID, and the server-side maps-key dependency that can disable town search. These are exactly the failure modes an agent would otherwise hit blind.

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 resource and the default view before any caveats, and every clause carries information. The final maps-key sentence is terse to the point of being cryptic, but nothing is padded or repeated.

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 tells the agent what each view returns ('the current business type, country, and place list for one location') and covers the search dependency. Nothing needed to call this correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: q is required for view=places (not stated in the schema), and it reinforces the account_id vs location_id preference and the Place ID confusion. Minor uplift only, since the schema descriptions carry most of the 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?

Opens with a specific verb+resource ('Read Google Business service areas') and immediately defines scope ('the towns and postcodes a location covers, up to 20'). The two-view structure (areas vs places) makes the read-only counterpart to manage_google_business_service_area unmistakable.

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 the default view, that q is required for view=places, and gives a fallback path ('add a place with its Place ID and name on the update instead') when no maps key is configured. It never names the sibling manage_google_business_service_area directly, so the write-vs-read routing 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the useful detail that the tool returns finished urls/video_url after polling, but says nothing about pagination, ordering, or behavior of dismissed jobs beyond what the schema already states. Adequate but not rich.

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 parallel sentences, one per type, with the job_id/omission behavior front-loaded in each. No filler, though the packing of parameters into the sentences makes it slightly dense 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?

With no output schema, the description usefully hints at the return payload (urls, video_url) and covers both modes of a 4-parameter tool. The main gap is absence of any note on result ordering or paging, but for a read-only list tool this is close to 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 coverage is 75%, so most parameters are already documented. The description largely restates schema content (job_id omission lists recent, status/limit filters) and the video-only nature of dismissed is already in the schema. It adds some mode-framing but little genuine semantic detail beyond the structured fields.

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 resource (AI generation jobs) and a specific verb behavior (list one by job_id or list recent), and splits the domain cleanly into type=image vs type=video. An agent can tell what it does at a glance. It stops short of 5 because the resource is a dense compound sentence rather than a crisp standalone purpose statement.

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

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

It explicitly says to poll this after generate_image and generate_video to retrieve the finished urls/video_url, which routes the agent from the sibling generation tools to this one. It gives no explicit 'when-not' or alternative for job retrieval, but the workflow context is concrete rather than implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, while the description adds useful context about ordering, returned fields, drop page defaults, output completeness, and pagination. There is minor ambiguity around page/limit values, but no annotation contradiction.

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

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

The description is front-loaded with purpose and packed with relevant guidance, with no filler sentences. Some dense parenthetical pagination detail slightly reduces immediate clarity, but each sentence mostly earns its place.

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

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

With no output schema, the description still covers key return fields (filename and time added), pagination behavior, and the completeness indicator. It could be more complete about limit constraints and asset identifiers, but it is adequate for a three-parameter list tool.

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

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

Schema coverage is only 33%, with offset alone documented in the schema; the description usefully explains drop_session_id and offset pagination, plus references public_url as an output field. Limit semantics remain vague and somewhat in tension with the schema: the schema has default 10 and maximum 50, while the description mentions up to 20 per drop page and 'offset + limit up to 1000' without reconciling these values.

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 the newest media assets for the authenticated user, with drop-specific usage via drop_session_id. It does not explicitly contrast with similar siblings such as list_posts or list_google_business_media, so sibling differentiation is incomplete.

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 conditions: after create_media_drop, pass drop_session_id; use public_url with validate_post / create_post; page with offset when the output says not all matching files are shown. It lacks explicit when-not guidance or a direct named alternative listing tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds that these are public PKCE clients for third-party integrations, but says nothing about pagination, ordering, or return shape.

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

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

Two tight sentences with the resource scope front-loaded and a clarifying clause about client type; 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 zero-parameter read-only list with no output schema, the description is nearly sufficient; it could mention the return contents or ordering, but nothing critical to invoking it 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 parameters and schema coverage is 100%, so the baseline is 4; the description adds no parameter detail because none is needed.

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 (List) and a well-scoped resource (self-serve OAuth developer clients owned by the user). It clarifies the resource over the bare name, but does not explicitly distinguish itself from the sibling manage_oauth_client.

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 scoping phrase 'owned by the user' and 'self-serve', but there is no explicit when-to-use statement, no exclusions, and no pointer to manage_oauth_client for mutations.

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=true, idempotent=true, destructive=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: parameter precedence when account_id and platform are both supplied, that credential platforms return credential_fields consumed by connect_account, and which view returns account-specific capabilities. It does not discuss response size, pagination, or auth requirements.

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?

Dense but front-loaded by view, and each clause carries usage or return information rather than filler. The heavy use of semicolons and stacked parentheticals makes it slightly hard to scan, and the opening noun-phrase fragment is not a clean lead sentence.

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

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

With no output schema, the description carries the burden of describing returns, and it does so per view (platform capabilities and limits, settings schema for one account, connection links with readiness and credential_fields). It never states the general response shape or how large the platforms view is, leaving a minor gap for a 6-param, 0-required discovery tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter meaning the schema cannot: which parameters apply to which view, the account_id-vs-platform precedence rule, and the reason account_id is preferred. The include_planned and target examples largely restate the schema enum, so not every addition is net-new.

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 enumerates the three distinct resources the tool surfaces (platforms, settings schemas, connection links) and ties each to a view value, so an agent understands this is a multi-view introspection tool rather than a simple list. The terse opener 'Platforms, settings schemas, and connection links.' is a fragment that doesn't name the verb, so the tool's scope has to be inferred from the view breakdown that follows.

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 for each view, including the preference for account_id over platform ('account_id wins if both are given') and the prerequisite ('needed before Instagram native tags/collaborators'). It names the alternative sibling create_connect_session with the exact condition that selects it ('guided flow with pollable status'), which is exemplary routing guidance.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses pagination semantics, that the response always reports whether the full result set was shown, timezone handling for reads and display, date-boundary inclusivity/exclusivity, the 366-day cap on counts, and that limit/offset/order are ignored in counts. That is exactly the kind of behavioral context annotations cannot express.

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?

It is a single dense paragraph that front-loads scope and then the view decision, and nearly every clause carries operational meaning. Minor waste comes from restating schema facts verbatim (limit default 20 / max 200, order='asc|desc'), which makes it read as a run-on.

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 16-parameter read tool with no output schema, it covers pagination, completeness signals, timezone behavior, and even one return field (approval.pending_client_approval). The main residual gap is that the shape of each returned post is not described, which matters given the absent output schema.

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 81%, so the baseline is 3; the description adds real meaning on top by explaining that counts requires scheduled_from/scheduled_to (with a 366-day ceiling) and how plain dates are read versus ISO date-times. Some parameters (platform, account_id, workspace_id) get no semantic treatment in either place.

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 the resource (posts), the scope (workspaces you belong to, teammates' posts, brand-locked seat visibility), and the two operating modes (list vs counts). It is specific enough that an agent can distinguish it from get_post or list_analytics without reading the schema, though it never explicitly names those 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 an explicit decision rule between the two views ('use it for "how many" or "is this month full" questions') and instructs the agent to keep paging until the output says everything was shown before drawing conclusions about totals. It stops short of stating when to prefer a different tool (get_post, list_analytics) for adjacent tasks.

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

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

Beyond the readOnlyHint/idempotent/destructive annotations, it discloses plan requirements (Pro or higher), returned fields (caption, rationale, account id), default status filtering, and pagination completeness behavior. This adds meaningful operational context an agent needs before calling it.

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

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

The description is front-loaded with the core purpose and stays tightly focused on what suggestions are, how to filter/page them, plan requirements, and related actions. Every sentence contributes useful selection or invocation 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 covers return fields and pagination completeness. It also covers filter defaults, plan requirements, and related sibling actions, making it complete enough 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?

The description explains filtering by account_id and status and mentions paging with offset, but schema description coverage is only 50% and the limit parameter is not described in the schema or the tool description. It adds some meaning but does not fully compensate for the coverage gap.

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

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

The description states a specific verb and resource: list proactive post suggestions, defined as evidence-based weekly drafts written in each account's learned voice with rationales. It distinguishes suggestions from actual posts and from sibling actions like dismiss_suggestion.

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: default status is pending, filtering is by account_id and status, paging uses offset, and the tool requires a Pro plan or higher. It names dismiss_suggestion and save_as_draft as alternatives for handling a suggestion, but does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so 'Read-only' is largely redundant. However, the description adds real context beyond annotations: visibility scoping ('only brands you can see') and the fact that the response includes caller permissions ('whether you may pause, resume, or publish missed posts'). It does not mention pagination or empty-state behavior, keeping it short of a 5.

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

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

Leads with the question the tool answers, then lists the payload, then the write alternative. Two short sentences plus a routing clause, no filler, every phrase carries information.

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

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

With no output schema, the description compensates by enumerating the returned information (pause status, visible brands, permitted actions), which is exactly what an agent needs to decide whether this call answers its question. Read-only annotations cover the safety profile, so nothing material 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?

Single optional parameter with 100% schema description coverage, so the schema already explains workspace_id and its default. The description adds nothing about the parameter (e.g., how to obtain the ID or scoping effects), which is exactly the baseline-3 case when structured fields carry the load.

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

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

States a specific verb+resource ('list publishing pauses' framed as 'Is publishing paused?') and enumerates exactly what it returns: workspace pause state, per-brand pause state, and the caller's pause/resume/publish-missed-posts permissions. It explicitly distinguishes itself from the mutating sibling manage_publishing_pause, so an agent can pick correctly 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?

Names the alternative tool and the condition that selects it: 'Read-only. Change it with manage_publishing_pause.' This gives a clean read-vs-write routing rule, including the implicit when-not-to-use (don't call this to change state).

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 bar is lower. The description still adds meaningful disclosure: delivery history is opt-in and may be absent, and the payload deliberately omits the signing secret and request body. Pagination behavior is not described, keeping it from a 5.

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

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

Three compact sentences, front-loaded with the primary list behavior before the secondary view. Every sentence contributes, though 'stays off until it is switched on' is slightly vague about who enables it and pronoun references to 'that history' and 'it' require mild inference.

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

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

For a read-only list tool with no output schema, the description compensates by naming the returned fields and the deliberate data omissions. Remaining gaps are pagination semantics and workspace scoping, which the schema exposes only partially and the description does not address.

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 40%, so the description must carry weight. It explains the critical enum parameter view and the webhook_id dependency ('webhook ID from view=webhooks') well, but says nothing about limit, offset, or workspace_id, leaving three of five parameters undocumented in both schema and 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 description opens with a specific verb and resource ('List API webhook subscriptions') and enumerates what is returned (event filters, active state, delivery status), then explains the secondary view=deliveries mode. It is clear what the tool does, but it never explicitly contrasts itself with the sibling manage_webhook or create_webhook, so sibling differentiation is only implied by the verb.

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 useful in-tool guidance: view=deliveries requires a webhook_id taken from view=webhooks, and delivery history is disabled by default so results may be empty. However, it offers no when-not-to-use guidance and does not route the agent to manage_webhook or create_webhook for related operations, leaving alternative selection to inference.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial operational context: what is returned, what API access means, who sees key counts and AI app connections, and the brand-limited visibility rule. This goes well beyond the structured safety 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?

The description is front-loaded with the purpose and returned data, then moves to auth requirements. Every sentence carries distinct information: return contents, API access meaning, permission scoping, and OAuth conditions, with no redundant 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?

There is no output schema, so the description correctly explains the return shape (members, invites, seats, per-member details). Combined with annotations covering safety and idempotency, and the description covering auth and visibility rules, an agent has everything needed to call the tool correctly.

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

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

Schema description coverage is 100% and there is only one parameter (workspace_id), which the schema already describes as coming from whoami. The description adds no additional parameter syntax or formatting detail, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'List the people in a workspace', then enumerates the exact members and invites returned. It distinguishes itself from the sibling manage_workspace_member by being purely a read operation with no mutation language.

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 auth and context prerequisites: 'Works with an API key that has the Manage team permission' or OAuth when the user is an owner or admin. It does not explicitly name when to choose this over alternatives, but the read-only framing and sibling names make the use case 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?

Goes well past the annotations (destructiveHint=true) by disclosing the actual archive consequences: the brand leaves the active list, connected accounts stay connected, and scheduled posts still publish. It also explains the two-call preview/confirm handshake and what the preview counts, which is the kind of side-effect detail an agent cannot get 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?

Organized action-by-action and front-loaded with the verb set. The phrase "Pass confirm=true only after the user agrees" is repeated verbatim for create and update, and the archive paragraph could be tightened, but 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 three-action, eight-parameter mutation tool with no output schema, the description covers prerequisites, per-action field requirements, the confirm workflow, and the post-archive state. An agent has everything needed to call it correctly and to explain results to a user.

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 description still maps parameters to the action that consumes them (create needs name and workspace_id; update needs brand_id plus the editable fields; archive needs preview_id). This mostly mirrors the schema's conditional notes rather than adding new syntax or format detail, so it is a slight enhancement rather than a full complement.

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 set and resource: "Create, update, or archive a brand." Each of the three actions is then expanded with its own required fields, so an agent can distinguish the mutation tool from list_brands 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 gates each action: "admin only" for all three, action=archive must be previewed then confirmed, and workspace_id should come from whoami "when the key is not already scoped." The confirm rule is stated per action, leaving no inference needed about sequencing.

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 (destructiveHint=true, idempotentHint=false): it distinguishes which actions are reversible ('update ... reversible, no confirm needed') from the irreversible one, flags delete as admin-only, and describes the preview_id handshake that gates reply and delete. This is exactly the behavioral context an agent needs for a mutating 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?

One dense paragraph, but it is front-loaded with the auth requirement and purpose before the three actions, and every clause carries meaning (platform limits, reversibility, preview flow). It reads as a run-on sentence, which costs it a point.

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, three-action tool with no output schema, the description covers permissions, platform exclusions, reversibility, and the preview/confirm return value (preview_id). It does not describe the success response for update or reply, leaving a minor 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 already 100%, so the baseline is 3, but the description adds real value by grouping parameters by action (which fields apply to reply vs update vs delete) and by treating type=private as Instagram-only. It stops short of adding syntax or format detail beyond what the schema states.

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

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

Opens with a specific verb+resource ('Act on an inbox comment') and then enumerates the three actions with their platform scope. It clearly distinguishes itself from the sibling list_comments, which is the read counterpart referenced by comment_id.

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

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

States per-action when-to-use, plan/permission prerequisites (Pro plan or higher plus posts:write, admin only for delete), and an explicit alternative when an action is unavailable ('Threads replies cannot be deleted, hide them instead'). It also requires the preview-then-confirm sequence before irreversible operations.

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

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

Annotations only declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true; the description goes well beyond that by disclosing the 24-hour messaging window, that Threads has no DMs, the two-step preview/confirm safety flow with preview_id, and the 30s/60s sync cooldown. These are material behavioral traits an agent needs before calling, and none of them contradict 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?

Dense but well-organized: it front-loads the tool's purpose and access requirement, then groups details by action. Every clause carries information, though the single long block sentence is slightly harder to scan than a broken-out structure would 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 multi-action mutation tool with no output schema, the description covers everything needed: which actions exist, their required inputs, the preview/confirm return-handshake (preview_id), platform constraints, rate limits, and account prerequisites. Nothing essential is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description layers on meaning the schema does not: it ties confirm to the preview_id flow, explains the cooldown semantics of sync, notes sync_type defaults and the comments-only limitation of Threads/LinkedIn, and points to provenance tools for account_id and conversation_id. This meaningfully exceeds the schema's terse field hints.

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+resource ("Act on the social inbox") and enumerates the two concrete actions with their targets (Instagram/Facebook Page DM replies, pull inbox data for four platforms). It distinguishes itself from siblings by naming the related tools (list_conversations, list_accounts) that supply its inputs, so an agent can place it correctly in the toolset.

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 conditional guidance: plan requirement (Pro or higher plus posts:write), the preview-then-confirm protocol for send, the 24-hour window, and per-platform cooldowns. It stops short of explicitly stating when NOT to use it versus alternatives such as list_conversations or manage_comment, so it is clear context without full exclusion 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/non-readOnly, and the description adds substantial value beyond them: money is charged to the saved card on raises, batch minimum of 20, the confirm/preview_id handshake, and the 3D Secure/decline path that returns a payment link with nothing added. This is exactly the extra behavioral context the annotations cannot 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?

Dense but front-loaded: the core action is stated first, then money implications, then permissions, then the confirmation workflow. Every clause carries distinct, 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 steps in to explain what the quote returns (preview_id and expected_ fields) and what a decline/3DS attempt yields (a payment link, nothing added). For a money-moving mutation tool, everything an agent needs to call it correctly 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 0%, so the description must carry parameter meaning, and it mostly does: action=set, extra_accounts as the desired TOTAL (0 removes all, add 20+ at a time), confirm, preview_id, and the expected_ fields from the quote. workspace_id and expected_interval are not explicitly explained, leaving a small 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?

Names specific verbs (Buy, raise, lower, remove) and the exact resource (Agency extra-account slots), including the action=set semantics. No sibling tool operates on extra-account slots, so the agent can distinguish it immediately.

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 prerequisites (Owner only; billing:write scope) and a full two-step workflow: call without confirm for a quote/preview_id, then call again with confirm=true after user agreement. This is precise when-and-how guidance rather than implied context.

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?

Despite annotations already flagging destructive=true and openWorldHint=true, the description adds genuinely new behavior: the two-call preview/confirm protocol with preview_id, and critically that while location edits are off a confirm "changes nothing and does not call Google." It also discloses the shared business-management connection, which agents can't infer from annotations.

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

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

Purpose and the two actions are front-loaded, then the safety-critical gating rule. It runs long at nine sentences and repeats schema detail (HH:MM, attributes/has_wifi, day names) that the schema already carries, but every sentence is informative rather than 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 destructive, 8-parameter tool with nested objects and no output schema, the description covers the mutation protocol, the blocking prerequisite, the external API call behavior, and explicit scope exclusions. An agent has what it needs to avoid a silent no-op or an unapproved write.

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 per-parameter meanings (action enum, preview_id, regular_hours shape, HH:MM and attribute naming) are already fully documented in the schema, and the description largely restates them. It does usefully bind each parameter set to its action, but that cross-reference is already implied by the schema's own per-param descriptions.

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

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

Opens with a specific verb+resource ("Change regular opening hours or attributes on a Google Business location") and immediately enumerates the two action modes. It also carves out scope by stating it does not touch name, address, phone, or website, which separates it from the other manage_google_business_* 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?

Clearly states when each action applies (action=update_hours vs action=update_attributes) and that both must go through preview-then-confirm. It also gives the prerequisite that location edits must be switched on, though it never names the alternative tool to use for the name/address/phone/website changes it excludes.

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 non-idempotency, and the description adds value beyond them: delete is 'permanently remove' from the public profile, COVER/PROFILE are single-slot (implicitly overwriting the existing image), and the preview/confirm gate must be shown to the user before committing. That is exactly the destructive/mutation context 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?

Front-loaded with the resource then action=add / action=delete / shared-flow segments, and every sentence carries actionable content. It is dense and slightly packed, but there is no filler to cut.

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 10-parameter destructive mutation with no output schema, the description covers prerequisites, per-action requirements, overwrite semantics, and the confirm workflow. An agent has everything needed to call it correctly without further discovery.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds decision-relevant meaning by binding parameters to actions (source_url/category for add, media_name for delete) and clarifying the COVER/PROFILE single-slot behavior and preview_id reuse. It stops short of explaining every field, but meaningfully exceeds 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?

Names a specific resource (Google Business Profile gallery of photos/videos on Maps and Search) and two explicit operations (add, delete). It also points at the relevant siblings (upload_media, list_google_business_media), so an agent can distinguish it from list_google_business_media or upload_media without opening a 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 when-to-use routing per action (add requires source_url+category sourced from upload_media; delete requires media_name from list_google_business_media), plus the mandatory two-step preview-then-confirm flow with the exact condition to set confirm=true. Nothing is left to inference.

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

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

Goes well beyond annotations by disclosing the two-step preview/confirm safety gate, that the preview echoes the exact reply text, location and review name for verification, that suggest_reply consumes the AI Caption Assist allowance and does not post, and that action=reply may update an existing owner reply. These are the details an agent needs to avoid an unreviewed destructive write.

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 resource, then ordered action by action, with the cross-cutting preview rule last. Dense but every clause carries operational meaning; the nested parenthetical in the final sentence is slightly hard to parse but not wasteful.

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 14 parameters, the description supplies the return shape that matters most (preview_id plus echoed review metadata for the confirmation step). It is silent on what suggest_reply returns (presumably `count` suggestions in `tone`) and on the success response for reply/delete_reply, which leaves a modest gap.

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