Saypage

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

Annotations only declare destructive/openWorld/not-readOnly; the description adds substantial behavior beyond them — prior comments are never answered, arming binds to the first post at its first comment, arming is paid with one armed automation per account, plan-limit accounting, and the published-page requirement.

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 structured bullets per mode. It is long, but nearly every sentence carries non-obvious state-machine behavior, so little 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?

Output schema exists, so return values need no explanation. For a stateful activation tool, the description covers both branches, edge cases (conflicting keyword → draft), billing constraints, and preconditions.

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 required parameter with 100% schema coverage, so the baseline is 3. The description references provider_media_id (an attribute of the automation, not an input to this call) to explain mode selection, but it adds nothing about automation_id itself.

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

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

States a specific verb ('turn on') and resource ('automation'), and immediately distinguishes the two modes (on a post vs. armed without a post). An agent can separate this from pause_automation, create_automation, or delete_automation 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?

Explains in detail when each mode applies (with provider_media_id vs. without) and what happens at binding time. It does not explicitly name the sibling to choose instead when a user wants the opposite (pause/disable), so routing is implied rather than spelled out.

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 readOnlyHint=false, but the description adds substantial context beyond them: old addresses redirect for a year and stay reserved, a site can move at most 3 times a year, and the `outcome` field reports created/moved/unchanged. This is exactly the kind of side-effect and rate-limit disclosure annotations cannot carry.

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

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

Front-loaded with the purpose and the 'rarely needed' caveat, then organized into scannable bullets covering each branch. Despite its length, every sentence carries actionable information (redirects, reservation, move limit, outcome values), so nothing is wasted.

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

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

For a single-parameter mutation tool with a 100%-covered schema and an output schema, this description covers everything an agent needs: when to call it, when it's a no-op, what it destroys, and what the outcome field means. Return-value detail is rightly left to the 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 description coverage is 100%, so the baseline is 3, and the schema already documents the handle-derivation fallback. The description adds the no-op semantics ('No `subdomain`, or the current one: changes nothing') and the address-mapping example, which goes 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 verb+resource ('Choose the address of the user's site, or change it') and immediately distinguishes itself from siblings by noting create_page already creates the site and get_account shows the current address. An agent can tell exactly what this 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?

It explicitly frames the tool as 'Rarely needed', names the alternatives (create_page, get_account), and gives the precise conditions under which each branch fires: no site yet, site already exists, or no subdomain/current one. It even instructs the agent to ask the user first and remind them about the Instagram bio link.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing the moderation behavior: refused images are never served, the error explains why, and the agent should tell the user and request a new image. This is exactly the kind of failure-mode context an agent needs and 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?

The primary purpose and return value are front-loaded in the first sentence, and the moderation caveat follows as actionable guidance. Slightly sprawling due to the mid-sentence line break, but 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?

An output schema exists, so return values need not be re-explained, and the description covers the critical edge case (moderation refusal and recovery). An agent has everything needed to call this correctly and handle failure.

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

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

Schema coverage is 100% and the single asset_id parameter is already documented as coming from start_image_upload. The description's reference format (_img/<id>.jpg) describes the return value rather than adding 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+resource ('Finish an upload') and its output ('returns the reference to use in the page'). It is clearly distinguishable from the sibling start_image_upload since this is the completion step of the same flow.

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?

'Finish an upload' plus the schema note tying asset_id to start_image_upload makes the sequencing clear. It doesn't explicitly name start_image_upload as the prerequisite step or state when not to call it, but the context is unambiguous for an upload-completion 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 declare the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the safety basics are covered. The description adds a genuinely non-obvious behavioral fact the name does not imply: this call also publishes the video, and a preview_url is available first. It omits idempotency and what happens if the upload was never started.

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

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

Two short sentences, zero filler, and the primary action ('finish a video upload, then publish it') is front-loaded ahead of the secondary UX advice. Every clause carries information.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description supplies the crucial side effect (publishing) and the preview affordance. A brief note on when this fails or that it must follow start_video_upload would make it complete.

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

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

Schema description coverage is 100% for the single video_id parameter, and the schema already says it comes from start_video_upload. The description adds no additional meaning (format, validation, or failure behavior) beyond what the schema states, so the baseline 3 applies.

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

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

The description names a specific two-step action (finish the video upload, then publish it) and explicitly names the sibling tool that performs the publish (publish_instagram_video). That distinguishes it from confirm_image_upload and start_video_upload without opening schemas. It stops short of a fully self-contained statement of what 'finish' validates.

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 one concrete usage instruction: offer the user `preview_url` to watch before publishing. That implies the intended workflow ordering, but it never states when this tool should be called versus start_video_upload, confirm_image_upload, or publish_instagram_video directly, and gives no preconditions (e.g., upload must be completed).

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 safe read-only profile; the description goes well beyond them by disclosing the return payload (connect_url), the out-of-band approval flow through Instagram and saypage.ai, and the explicit permission boundary (no publishing rights requested). That is exactly the context an agent needs before invoking.

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

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

Three short sentences, front-loaded with the action and the returned value, then the follow-up step, then the scope caveat. Every sentence carries operational 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?

An output schema exists, so return values need not be enumerated, yet the description still names the one field the caller must act on. Combined with the next-step pointer to get_account, an agent has everything needed to run this tool correctly.

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

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

The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool applies. The description correctly spends no words on parameters.

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 ('Start connecting the user's Instagram professional account') and scopes it to the professional account type. It is clearly separable from siblings like prepare_instagram_post or get_instagram_publishing_link, which it names.

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 the full usage sequence: call this, hand the returned connect_url to the user verbatim, wait for the Instagram approval round-trip, then call get_account. It also explicitly rules out a nearby concern ('This never asks for permission to publish posts') and routes that need to get_instagram_publishing_link.

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 openWorldHint=true, but the description earns its keep by explaining why: the DMs 'speak in the user's name', so consent is required, and activation may fail leaving a draft with a stated reason. It also documents the exact message/button sequence and follow-gate branching, which 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?

Four short paragraphs, front-loaded with the trigger and target, then consent, then flow, then failure recovery. Dense but each paragraph adds a distinct concern; the repeated language reminders echo schema text rather than adding new information.

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

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

For a 16-parameter tool with an output schema, the description covers the trigger, the user-consent workflow, the message flow, and the failure path. It leaves out operational details such as account/plan prerequisites or whether an automation is scoped per-post, but nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the field-level docs by tying parameters into a temporal flow (opening_message + its button, then link_message + link button + extra_link_buttons, with follow_request_message substituted when follow_gate is true) and by stating the 20-character button-label constraint and language rule.

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 opening sentence gives a specific verb+resource+trigger: 'DM a link to followers who comment `keyword` on the post', with the target being either a `page_id` or a `url`. An agent can distinguish this from siblings like update_automation, activate_automation, and list_automations 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?

It gives explicit pre-call guidance ('Confirm the post, keyword and messages with the user before calling this') and routes to a sibling on failure ('fix that, then activate_automation; never create a second one'). It stops short of naming update_automation as the alternative for an existing automation, so the when-not-to-create case is only implied by 'never create a second one'.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real context beyond them: the draft is not public, the response carries publication-blocking feedback.issues, and there is a shell/file-based variant. It stops short of error or permission semantics, but this is well above the annotation baseline.

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 lines, front-loaded with the one-sentence purpose before any workflow detail. Every sentence carries a distinct instruction; nothing is repeated from the schema or annotations.

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

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

An output schema exists so return values need no prose, yet the description still flags the one response field that changes agent behavior (feedback.issues). Prerequisite, follow-up tools, and the shell branch are all covered for a 2-parameter creation 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 the baseline is 3, but the description adds meaning the schema cannot: it explains when to omit html (shell workflow) and why the default-null html is acceptable, which is precisely the ambiguity the schema leaves open.

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

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

States a specific verb and resource with scope: 'Save a new page as a draft. Nothing is public yet.' This immediately distinguishes it from publish_page and update_page, and an agent can tell it apart from its siblings 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?

Prescribes the full workflow and names the alternatives at each step: call get_page_guide first, fix blocking feedback.issues with update_page, then surface preview_page's link. The conditional shell path ('omit html: run the returned command') covers the alternate invocation route.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the irreversibility profile is covered by structured data. The description adds the user-confirmation directive, which is genuinely beyond the annotations, but says nothing about permanence, cascading effects on automation activity, or scope of deletion.

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

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

Two short sentences, imperative and front-loaded; the action comes first and the safety directive second. Nothing is padded or repeated from the title or schema.

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

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

An output schema exists, so return-value explanation is unnecessary, and the destructive nature is disclosed via annotations plus the confirmation note. Still, for a permanently destructive tool the description omits whether deletion is recoverable and whether paused/active state matters, leaving gaps against 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?

Schema description coverage is 100% for the single automation_id parameter, and the description adds no format, source, or lookup guidance for it. With the schema doing all the work and no compensating detail, the baseline of 3 applies.

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

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

States a specific verb and resource ("Delete an automation") that is unambiguous on its own. It does not, however, distinguish itself from adjacent siblings like pause_automation, disable_instagram_publishing, or update_automation, which are the near-miss alternatives an agent might pick.

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

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

"Ask the user first" is a real usage precondition and the only guidance given. There is no mention of when deletion is preferred over the reversible alternatives (pause_automation) or any prerequisite/authorization context, so the guidance is implied 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 destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: the entry disappears from list_images immediately while quota is only freed after ~30 min cleanup, uploads can still be refused in that window, and Instagram copies survive deletion. This is exactly the hidden-behavior context an agent needs before calling an irreversible 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 the action and its purpose, then failure conditions, then side effects, then the caution. Every sentence carries operational information; there is no filler despite the length.

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?

An output schema exists, so return values need no explanation, and the description covers what an agent cannot infer: refusal conditions, delayed quota reclamation, Instagram copy retention, and the requirement to confirm with the user first.

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

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

Schema description coverage is 100% and the single parameter already documents its accepted sources ('id' from list_images or the _img/... reference). The description reinforces where the id comes from but adds no 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?

States a specific verb and resource ('Delete an uploaded image') with the scope qualifier 'for good' and the rationale (quota room). An agent can immediately distinguish it from delete_video, delete_page and other siblings without opening any schema.

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

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

Explicitly states the precondition for success ('refused while a page uses it, as a draft or online'), how to diagnose it (list_images shows `used_by`), the remediation (remove from those pages and save or publish first), the unaffected case (Instagram posts keep their own copy), and the human-in-the-loop requirement ('Ask the user 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 declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is largely covered. The description still adds genuine value by emphasizing irreversibility ('for good') and imposing a user-confirmation requirement, which annotations do not express. It stops short of mentioning auth/permission needs or rate limits, so it is not exhaustive.

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

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

Two short sentences with zero filler, front-loading the destructive action before the caution and the alternative. Every clause earns its place.

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

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

An output schema exists, so return values need not be explained, and annotations plus schema cover the structured contract. The description supplies the remaining decision-relevant context: permanence and the required user confirmation.

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 (account_id, comment_id) are documented in the schema, so the description correctly leaves parameter detail to the schema. It adds no syntax, format, or sourcing nuance beyond that baseline.

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

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

The description states a specific verb and resource ('Delete a comment under one of the account's posts') and immediately signals permanence with 'for good', distinguishing it from the reversible sibling hide_instagram_comment. An agent can tell exactly what this 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?

It gives an explicit precondition ('Ask the user first') and names the alternative tool plus the condition that selects it ('hide_instagram_comment is the reversible option'). Both when-to-use and when-to-use-something-else 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real context beyond them: deletion is permanent ('for good'), it also removes the draft, it requires user confirmation, and it can be refused by automation dependencies with specific remediation steps. That is exactly the kind of operational detail annotations cannot carry.

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

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

Front-loads the action and the user-confirmation rule in two tight sentences, with no padding. However, the second sentence's phrasing ('point it elsewhere or remove its button (update_automation), or delete it, first') is slightly tangled and takes a re-read 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 an output schema present, return values need no explanation, and the description covers the destructive scope, consent requirement, and refusal conditions. The only soft spot is the vague 'point it elsewhere' remediation, which an agent must map to update_automation on its own.

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

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

Schema coverage is 100% for the single page_id parameter, whose schema description is just 'Page id'. The description adds no format, source, or retrieval guidance for the id, so baseline 3 is appropriate when the schema does the documenting.

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

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

States a specific verb and resource ('Delete a page and its draft') and goes further by disclosing the cascading scope ('and its draft for good'), which distinguishes it from unpublish_page. An agent can tell what this tool destroys 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 an explicit precondition ('Ask the user first') and a clear when-not case: it is refused while an automation sends the page or has a button opening it, with the remedy (update_automation, or delete the automation first). It names a sibling as the fallback path, though it does not contrast with unpublish_page if the agent only wants to take the page offline.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds value beyond them with the failure mode ('refused while it is being published') and the timing semantics ('now rather than at its expiry'). It stops short of saying whether the deletion is recoverable.

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

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

Two short sentences, zero filler. The primary action and its timing distinction are front-loaded, with the refusal condition as a second, clearly separated clause.

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

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

The one parameter, output schema, and annotation safety profile are all covered outside the description, and the description contributes the non-obvious precondition. The main omission is whether the deletion is permanent or recoverable, which matters for a destructive one-way operation.

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

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

Schema coverage is 100% and the single parameter is already documented in the schema as the video's `id` from list_videos. The description adds no additional param semantics, 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?

Specific verb (Delete) plus specific resource (an uploaded video), and it distinguishes itself from the implicit expiry-based removal by saying 'now rather than at its expiry.' An agent can tell this apart from delete_image/delete_page at a glance by resource.

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

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

It gives concrete usage context ('e.g. the wrong file') and states a precondition ('Refused while it is being published'), which tells the agent when the call will fail. It does not name an explicit alternative tool, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuine value on top: the blast radius ('Pages, automations, comments and insights keep working') and the re-approval cost of reversing it, which 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?

Very short and front-loaded, leading with the action and urgency before the scope and reversal caveats. The trailing parenthetical naming the sibling tool is slightly awkward but earns its place.

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

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

With an output schema present, return values need no explanation. The description covers action, urgency, unaffected features, and reversal requirements, which is sufficient for a one-parameter state toggle.

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

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

There is a single parameter with 100% schema description coverage ('From get_account'), so the schema fully documents it. The description adds nothing about account_id, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Turn off publishing posts on this account'), which clearly distinguishes it from the publishing siblings like publish_instagram_post. It does not explicitly name a contrasting sibling, but the action is unambiguous.

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

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

Gives clear timing guidance ('Do it as soon as the user asks') and points to the reversal path via get_instagram_publishing_link, which acts as the alternative for re-enabling. It stops short of stating when NOT to use it, but the context is well established.

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

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

With readOnlyHint=true and destructiveHint=false already covering safety, the description adds substantial behavioral context: suggestion is for the agent to follow, bio_link limitation, can_publish_posts default and optional nature, monthly DM cap semantics with not_sent/plan_limit implications, and publish limit counting. These details are not in the annotations.

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

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

The description is front-loaded with the resource statement and usage instruction, and uses terse field annotations. It is longer than typical, but each paragraph addresses a specific field or behavior. Some output-field explanation could be trimmed given the output schema exists, keeping it from a 5.

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 output schema exists, so return values need not be described, and annotations cover read-only safety. The description still supplies all context an agent needs: when to call, how to read the suggestion, and how to interpret plan limits and publishing flags. 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?

There are zero parameters, so the baseline is 4. The description adds no parameter information because none exists; its field-level explanations pertain to the output schema rather than input parameters.

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 the resource (the user's Saypage account) and enumerates its contents: plan and usage, site address, Instagram accounts. It distinguishes this account-level tool from onboarding by specifying onboarding is for first-time use. An agent can identify the tool's scope without opening the schema.

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

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

Explicitly says to call this at the start of a conversation, and directs to onboarding instead the first time the user uses Saypage. This gives a clear when-to-use and an alternative for the excluded case. No further exclusions are needed for a no-param account getter.

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 establish the read-only, non-destructive, closed-world profile, and the description goes well beyond that: 13-month summary retention, 30-day username/comment retention, the plan_limit failure cause with a pointer to get_account, why an already-in-flight commenter is omitted, and an explicit prompt-injection caution about treating comment text as data. That is rich behavioral context an agent could not 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 and the prose is information-dense, with no filler sentences. It is on the long side because it enumerates every summary counter and stage name, some of which leans toward output-schema territory, but each enumeration carries domain meaning.

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

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

For a complex, retention-bounded analytics tool with an output schema, the description covers what matters: what the totals and per-entry stages mean, failure causes, data lifetimes, and a safety note on untrusted comment content. Nothing an agent needs to call or interpret it correctly is missing.

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

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

Schema description coverage is 100% (limit, before, automation_id are all documented in the schema), so the baseline is 3. The description implies newest-first ordering but adds no syntax, format, or pagination detail beyond what the schema already provides.

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

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

The opening line states a specific verb and resource: it reports who an automation DMed and how far each recipient progressed, ordered newest first with totals. This is unambiguous and an agent can distinguish it from list_automations or get_account 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?

The description makes the usage implicitly clear (inspect per-recipient DM progress for a given automation), but it never states when to reach for this tool versus siblings, nor any exclusions or prerequisites. Usage must be inferred from the content it promises to return.

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 readOnly/openWorld/non-destructive profile, and the description adds substantial context: the 100-follower threshold for follows/unfollows/demographics, a possible 48-hour data lag, and the `unavailable` field semantics with guidance not to guess. That is rich behavioral disclosure beyond 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?

The metric enumeration is dense but front-loaded and every clause carries information (metrics, unavailable handling, thresholds, cross-tool routing). Slightly long, but nothing is wasted.

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

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

An output schema exists so return-value structure needn't be explained. The description fully covers the permission requirement, edge cases (100 followers, 48h lag, missing metrics) and cross-tool boundaries, leaving no gap for an agent to call it correctly.

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

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

Schema coverage is 100%, so days, account_id and demographics are already documented in the schema, including the 100-follower note. The description references `days` only inline and 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?

The description states a specific verb and resource (account insights over the last `days` days) and enumerates the exact metrics returned. It implicitly distinguishes from get_instagram_post_insights (post-scoped) by operating at account level and explicitly separates from get_page_stats for bio-link taps.

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 the prerequisite ('Needs `can_read_insights` in get_account') and routes the agent elsewhere for bio-link taps via get_page_stats. It also tells the agent to surface Instagram's `unavailable` reasons. No explicit when-not-to-use, but usage context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds a useful behavioral note that a `suggestion` field may be present and should be followed, plus the shape of returned data, but says nothing about auth scope, rate limits, or behavior when the post id is stale.

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

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

A single dense sentence that front-loads the returned content and appends the cross-references, with no filler. It is slightly cryptic due to backticked field names in prose, but nothing is wasted.

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

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

With an output schema present, the description need not enumerate return values, yet it helpfully names the key ones and flags the `suggestion` follow-up behavior. Combined with fully documented input params, an agent has enough to call it correctly; only the sibling-boundary guidance is thin.

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

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

Schema coverage is 100% and both parameters are documented there (account_id 'From get_account', provider_media_id 'from list_instagram_posts'). The description's mention of `comment_keyword` and `suggestion` refers to output fields, not inputs, so it adds no parameter-level meaning; 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 what the tool returns for a single post (full caption, counts, comment status, image URL, comment_keyword) and explicitly points to the sibling list_instagram_posts as the source of the post identifier, which separates it from list-style tools. It never uses a direct verb like 'Retrieve', but 'One post in full' is unambiguous enough for selection.

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 through cross-references: 'see list_instagram_posts' for the post id and 'Follow `suggestion` when present' gives one conditional behavior. There is no explicit statement of when to prefer this over get_instagram_post_insights or preview_instagram_post, so an agent must infer the boundary.

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/openWorld/destructive, so the description appropriately adds context instead: the `unavailable` reason field, the can_read_insights permission requirement, the 24-hour live-only window for story replies/navigation, and the sparse post object (id, type, link, date). It does not mention rate limits or pagination, but it adds substantial behavioral value beyond the annotations.

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

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

The return-value inventory is front-loaded and dense, and nearly every clause carries decision-relevant information. It reads as a long run-on, but the length is earned by the breadth of per-kind metric differences.

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

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

With an output schema present, the description need not explain returns, yet it still covers metric content, availability reasons, auth prerequisite, and sibling contrast. The only noticeable gap is an explicit pointer to get_instagram_insights for account-level totals.

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

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

Schema description coverage is 100% and both parameters already carry their source hints ('From get_account', 'from list_instagram_posts'). The description adds no parameter-level syntax or format detail beyond what the schema provides, 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 ('One post's numbers') and enumerates exactly which metrics are returned, including per-post-kind variations. It explicitly distinguishes itself from the sibling get_instagram_post by noting that tool has the caption and image.

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 prerequisite ('Needs can_read_insights in get_account') and names get_instagram_post as the alternative when caption/image is wanted, effectively telling the agent when not to use this tool. It does not, however, explicitly contrast with the account-level get_instagram_insights 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the tool cannot enable anything itself, only user consent on Instagram's screen does, and publishing never happens without a separate publish_instagram_post call. However, it does not describe any rate limits, permission requirements, or link expiry, so it is a solid supplement rather than exhaustive.

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 outcome in the first sentence, and the consent-flow guidance follows logically. It is somewhat verbose and emphatic ('This tool turns nothing on and cannot'), and a couple of sentences restate the same no-publishing-without-consent point, but nothing is wasted enough to hurt usability.

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?

An output schema exists, yet the description still clarifies the meaningful return distinction (publishing: true with no link when already enabled). Combined with the consent flow, defaults, and the adjacent tools named, an agent has everything needed to call and act on 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 description coverage is 100% and there is a single account_id parameter already documented as 'From get_account'. The description adds no parameter-level meaning at all, which is acceptable given the schema does the work; 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 outcome: returns the link where the user authorizes Saypage to publish on Instagram. It is clearly distinguishable from publish_instagram_post (which actually posts) and disable_instagram_publishing (which turns it off), so an agent can tell what this tool does without opening any schema.

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

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

Explicitly covers when to use it (optional feature, off by default, mention once and never push), what to do with the result (hand over publishing_url verbatim and wait), and the already-enabled case (returns publishing: true with no link). It also names the related tools that gate and reverse the behavior.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the meaningful detail that what is returned is the *draft* HTML and that edits flow through update_page, but says nothing about permissions or state beyond that.

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 compact sentence with the resource and its key payload front-loaded and no filler. Every clause earns its place, including the workflow pointer.

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?

An output schema exists, so return structure need not be explained, and only one parameter is involved. The description covers what is returned and the update cycle, making it essentially complete, though the draft-state concept could be elaborated slightly.

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

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

There is one parameter and schema description coverage is 100%, so the schema already documents page_id. The description adds no parameter detail (no format, source, or identifier semantics), leaving the baseline 3 appropriate.

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

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

The description specifies the resource returned ('A page') and its payload ('current draft HTML'), which implicitly conveys retrieval. However, it never states an explicit verb and does not distinguish itself from adjacent siblings like get_page_guide, get_page_stats, or preview_page.

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 parenthetical 'edit this and save it with update_page' implies the workflow and routes to the update_page sibling, which is useful. But it gives no explicit when-to-use versus get_page_stats, preview_page, or list_pages, so guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context about what the guide contains (user questions, design bar, rules with examples) but discloses no behavioral traits beyond the safety profile, so a 3 is appropriate.

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

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

A single front-loaded sentence names the purpose and the call timing, then uses a coloned list to summarize the guide's contents. It is dense but every clause carries information; only minor tightening is possible.

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?

An output schema exists, so return values need not be explained, and the description adequately conveys the tool's purpose and call trigger. It is complete enough for correct invocation, with only marginal gaps around how the guide relates to specific sibling tools.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no inputs are required ('Call it once'), and there is nothing further to document.

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 function: it returns guidance on 'How to make a Saypage page', which clearly distinguishes it from siblings like create_page, update_page, and preview_page. An agent can tell this is a reference/instructions tool 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?

It gives explicit timing ('Call it once before writing any page HTML, even a small edit') and an imperative to follow the result, covering nearly every applicable case. It does not, however, explicitly name an alternative sibling or delineate a when-not scenario, so it stops short of the top tier.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: it explains that clicks inside pages are not counted, that every page load counts including link-preview bots, and gives detailed semantics of each channel tag, including a warning about mis-tagging Instagram bio links. This rich context is valuable for correct interpretation.

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 front-loads the core purpose but then becomes a dense wall of text explaining channel taxonomy. Much of the channel detail is useful for interpreting output, but the explanation is verbose and includes a warning that seems aimed at a different context, making it less concise than ideal.

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

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

Given that an output schema exists and annotations cover safety, the description provides the necessary domain context for interpreting results—especially the meaning of each channel and the counting rules. It is complete enough for an agent to understand what the tool returns and how to read the statistics.

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

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

Schema coverage is 100%, and the single parameter `days` is fully documented in the schema as 'Look-back window in days' with default and min/max values. The description mentions 'over the last `days` days' but adds no further syntax, format, or behavioral detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: it returns visit statistics for the user's pages, broken down by views, daily views, channels, referrers, and countries. It clearly distinguishes itself from siblings like get_instagram_insights and get_page by focusing on page analytics rather than Instagram or page metadata.

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

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

The description explains what data is returned but never says when to use this tool versus alternatives (e.g., get_instagram_insights or get_account). There is no guidance on when to call it, when not to, or which sibling would be more appropriate in different scenarios.

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=false, but the description adds real substance: the comment stays visible to its author, the action is reversible, and the account's own comments always show. It does not mention permission requirements or rate limits, so it is good but not exhaustive.

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

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

Two sentences with zero filler; the primary effect (hide from everyone but the author) is front-loaded, with the reversibility contrast following.

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?

An output schema exists so return values need not be explained, and annotations carry the safety profile. Combined with the description's behavioral detail, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'or show it again' mirrors the schema's own 'false shows a hidden comment again' text rather than adding syntax or format detail beyond 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?

Specific verb (hide/show) plus resource (Instagram comment), with an inline gloss of the effect ('from everyone but its author'). It explicitly names the sibling it is not, delete_instagram_comment, so an 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?

It names the alternative tool and the key tradeoff ('reversible, unlike delete_instagram_comment'), which is strong routing guidance. It stops short of stating explicit when-not conditions (e.g., when permanent removal is actually required), leaving that to inference.

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

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

Annotations already establish read-only, non-destructive, closed-world behavior, so the description's job is to add context — and it does: it enumerates status values (active/waiting/paused/draft), explains that `post` is null while awaiting the next post, and discloses a 13-month retention window with counting caveats for links_sent. That retention/counting detail is genuine behavioral context the agent cannot get 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?

Front-loaded with the resource definition, then a scannable bullet breakdown of the three returned fields. Each bullet earns its place, though the links_sent bullet is dense enough that its counting rules require a second read.

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

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

Complete for a read-only zero-parameter list tool: purpose, field semantics, and a sibling pointer are all present. Because an output schema exists, the field-by-field enumeration is partly redundant, but the semantic rules attached to it (counting, retention, null post) justify its presence.

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. There is no parameter surface for the description to illuminate or obscure.

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

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

Clearly identifies the resource — the user's Instagram automations, defined as 'keyword on a post -> DM with a link' — so an agent knows exactly what set is being listed. It distinguishes itself from get_automation_activity by scoping that sibling to per-recipient DM detail. It never states the verb 'lists/returns all' outright, relying on the name to carry that, which keeps it just short of a 5.

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

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

The closing sentence points to get_automation_activity for 'who got which DM and where people stopped,' which is a useful alternative pointer. However, there is no explicit when-to-use framing for list_automations itself and no stated exclusions, so the guidance is implied rather than directive.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context beyond annotations: account limits, the meaning of `reference` and `used_by`, and the deletion implication of an empty `used_by`.

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

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

The description is compact and front-loads the resource being listed. It is dense but slightly awkward in phrasing, and every clause carries relevant information 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?

With an output schema present and annotations covering the safety profile, the description provides enough context to call the tool correctly. It explains the key return fields and the deletion-related condition without needing to restate schema details.

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

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

The tool has zero parameters, so there are no parameter semantics to document. Baseline 4 is appropriate; the description instead adds useful meaning about returned fields, which is bonus context rather than a substitute for parameter 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?

States a specific verb and resource: the user's uploaded images, including returned fields and the quota context. It does not explicitly distinguish itself from sibling list tools such as list_videos, but the resource is unambiguous.

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

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

Usage is implied: inspect images and their `used_by` metadata, with an explicit deletion decision rule when `used_by` is empty. It does not state when to choose this over list_videos or other listing tools, and offers no broader when-not guidance.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), so the description's added value is the semantic explanation of the 'answered' and 'by_you' flags plus an explicit prompt-injection warning about untrusted comment text. That is real, non-obvious behavioral context an agent would otherwise miss, though pagination/return behavior is left to the output schema.

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

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

Two short paragraphs, front-loaded with the resource and ordering, and every sentence contributes (flag semantics and the injection caution). Minor waste only in the slightly informal framing 'Comment text is written by strangers'.

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

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

With an output schema present, the description needn't explain return values, and it does supply the one thing the schema cannot: meaning of the 'answered'/'by_you' fields and a security caution about untrusted content. Pagination via cursor is adequately covered by the schema, so only usage routing is missing.

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

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

Schema description coverage is 100%, so all three parameters (cursor, account_id, provider_media_id) are already documented in the schema, including cursor's 'next_cursor from a previous call' semantics. The description adds nothing about parameters, 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 resource ('a post's comments') with ordering ('newest first') and scope ('each with its replies'), which is clear enough to distinguish from get_instagram_post and delete/hide/reply comment siblings. It stops short of explicitly naming an alternative tool, so it is clear but not sibling-differentiating at the highest level.

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

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

Usage is only implied: an agent infers it should call this to read a post's comment thread, presumably after list_instagram_posts. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. get_instagram_post_insights vs this), so guidance is minimal.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description goes further by disclosing a real behavioral quirk: stories appear only while live (24h) and only on the first page, which affects pagination assumptions. It stops short of describing pagination mechanics or ordering guarantees beyond 'newest 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?

Front-loaded with the resource and ordering, then the selection guidance, then the caveats. Slightly fragmented across short paragraphs and parenthetical asides, 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?

An output schema exists, so return-shape explanation is optional, and annotations cover safety. The description still supplies the operational context an agent needs (live-story window, no comments on stories, the special meaning of comment_keyword and suggestion), leaving only minor gaps around pagination 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 description coverage is 100%, and both parameters (account_id, cursor) are documented in the schema itself, so the baseline is 3. The description's field explanations (comment_keyword, suggestion) refer to response fields rather than inputs, so they do not add parameter-level meaning.

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

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

States a specific verb and resource ('recent posts, Reels and stories, newest first, with like and comment counts') and scopes the result set precisely. It implicitly distinguishes itself from get_instagram_post (single post) and list_instagram_comments by framing itself as the discovery step for picking a post or finding comments.

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

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

Gives explicit intended uses ('to pick a post for an automation, or to find comments to answer') and an explicit when-not: stories take no comments, so never pick one for an automation. The agent is also told to follow `suggestion` when present.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is known. The description adds domain context (what libraries are and the exact-URL requirement), but does not disclose return format, pagination, or other behavioral traits beyond what annotations cover. With annotations present, this is 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 short sentences with zero waste. The resource definition is front-loaded, followed immediately by the key usage constraint. Nothing is extraneous.

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

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

For a simple zero-parameter list tool with a comprehensive output schema and clear annotations, the description supplies the essential domain info: what the libraries are and the exact-URL requirement. It falls short only in not explicitly stating when to invoke the tool, but the output schema covers return values.

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, so the baseline is 4 per the rubric. The schema is empty and no parameter semantics need to be conveyed in the 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 identifies the specific resource: open source libraries a page may load via <script src> or <link rel=stylesheet>. While it lacks an explicit verb like 'list,' the tool name and title supply that, and the description clearly distinguishes this resource from sibling tools like list_pages or list_images.

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

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

The second sentence ('Use the exact URL. Anything else must be inline in the page.') gives a usage constraint for the returned libraries, implying the tool should be consulted to know allowed external URLs. However, it does not explicitly state when to call this tool versus alternatives, leaving usage context implied rather than spelled out.

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

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

Annotations already declare this as a safe read (readOnlyHint=true) and non-destructive, so the safety profile is covered. The description adds genuine semantic context beyond the annotations: the meaning of each status (draft, published, taken_down) and review state (none, checking, rejected), including that a rejected publication leaves an earlier version online and that review_note carries the reason.

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 ('The user's pages') followed by the two axes of interest. It is a single dense sentence with nested parentheticals, but for three status values and three review states the length is justified and nothing is redundant.

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?

An output schema is present, so return values need not be enumerated, yet the description helpfully characterizes the status and review_state semantics the agent will see. For a zero-parameter, read-only list tool this is close to complete; only the lack of pagination/size context keeps it from a 5.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is no parameter semantics to add, and the description correctly spends its space on output-state semantics instead.

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 conveys that this returns the user's pages together with their status and review state, but it never states a verb (list/retrieve) and never differentiates itself from close siblings like get_page, get_page_stats, or preview_page. The bulk of the sentence is spent explaining field values rather than the tool's purpose, so the purpose is only implied.

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

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

There is no when-to-use guidance, no mention of when to prefer this over get_page or get_page_stats, and no exclusions. The agent is left to infer usage entirely from the tool name.

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

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

Annotations only declare read-only, non-destructive, closed-world. The description goes well beyond that, disclosing ordering, the full status vocabulary, and the semantics of each state: uploaded items wait until `expires_at` before publishing, published items carry a `permalink`, failed items carry an `error`, expired items were deleted unpublished. That is genuine 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?

Front-loaded with the core fact (whose videos, what kind, what order), followed by a compact status glossary. Every clause carries information; nothing is redundant padding.

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

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

With an output schema present, the description need not document return shapes — yet it usefully explains the status/note fields anyway. For a zero-parameter, read-only listing tool, 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 the baseline is 4; there is nothing for the description to clarify and it does not need to. It correctly avoids inventing filter syntax that the schema does not offer.

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 resource scope (the user's Instagram videos), an ordering guarantee (newest first), and defines the resource further by enumerating the lifecycle states a video can be in. An agent can distinguish this from list_images and list_instagram_posts 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?

Usage is implied — call it to enumerate the user's videos and see where each stands — but there is no explicit when-to-use framing, no stated precondition (e.g., after start_video_upload or before publish_instagram_video), and no pointer to alternatives such as list_instagram_posts. Minimum viable, with a clear gap.

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

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

With readOnlyHint already declaring the safety profile, the description adds genuinely new behavioral context: the returned `instructions` are meant for the agent, not the end user, and `connect_url` is only populated while no Instagram account is connected. These handling and conditional-state details go beyond the annotations, though return structure nuances are left to the output schema.

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

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

Front-loads what the tool provides, then the when-to-call condition, then handling caveats. Three sentences with no padding; the only minor inefficiency is that the connect-link detail trails after the usage guidance.

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 guide tool with an output schema, this covers purpose, trigger, and the two key output fields. Since the output schema exists it needn't explain return values exhaustively, but it could say a bit more about what the `instructions` contain or that the flow ends once Instagram is connected.

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

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

The tool takes zero parameters, so the baseline is 4. The description still meaningfully characterizes the two notable output fields (`instructions` and `connect_url`), adding value even though there is no input to document.

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+resource (welcome a new user / onboarding steps) and names the concrete artifacts returned (steps and an Instagram connect link), so an agent understands this is a guided-setup resource rather than an action. It doesn't explicitly contrast itself with the closest sibling, connect_instagram, but the purpose is unambiguous.

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

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

It gives explicit triggering conditions: call it the first time a user uses Saypage, or when they ask how to start or what Saypage can do. That is clear when-to-use guidance, though it names no when-not conditions or alternative tools.

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

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

Goes well beyond the destructiveHint=true annotation by spelling out concrete consequences: comments received while paused are permanently unanswered, in-flight followers still complete their flow, the automation no longer counts toward the plan limit, and the keyword remains attached to the post. This is exactly the side-effect detail an agent needs before mutating state.

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

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

The core action and its inverse lead, then three short clauses each deliver a distinct behavioral fact. No filler sentences and no repetition of the title.

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

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

An output schema and the destructiveHint annotation are already present, and the description covers the remaining decision-relevant unknowns (irreversible comment loss, plan-limit accounting, keyword retention, partial-flow behavior). 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 description coverage is 100% with a single required automation_id, so the schema carries parameter meaning. The description adds nothing about the id (format, source), which is acceptable at this coverage level but not value-adding.

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 ('Stop an automation from answering new comments') and immediately names the counterpart 'activate_automation' as the inverse, letting an agent separate the two without opening 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 points to activate_automation as the resume path and implies 'use this to halt replies,' so the when-to-use is clear. It does not distinguish pausing from delete_automation or update_automation, which are the other plausible siblings an agent might consider.

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 readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description adds real behavioral context beyond that: nothing is published yet, images outside 4:5 get cropped per `fit` or padded, carousels crop to the first image's shape, the container_id expires in 24 hours, and publishing must be enabled. These are non-obvious operational facts an agent would otherwise miss.

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

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

The purpose is front-loaded and almost every sentence carries operational information (crop rule, preview step, carousel rule, publish handoff, precondition). Minor redundancy between "without publishing it" and "Nothing appears on Instagram yet," but density is justified for the workflow it encodes.

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?

An output schema exists, so return values need not be explained, yet the description still names `cropped_to` and `container_id` to close the loop with preview and publish. For a non-destructive, open-world mutation with 7 params, the description covers prerequisites, side effects, and the downstream call needed to complete the task.

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 and the schema does most of the work. The description nonetheless adds workflow-level meaning to `fit` and `images` by tying them to the crop-to-first-image carousel rule and to the preview step, which the schema does not state. It does not add anything for caption, alt_texts, or pad_color.

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 opening sentence gives a precise verb+resource+scope: "Build an Instagram post from uploaded images, without publishing it." That immediately distinguishes it from the sibling publish_instagram_post and from generic upload tools. An agent can identify the tool's role without opening the schema.

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

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

It explicitly routes to alternatives: run preview_instagram_post first when images get cropped, then call publish_instagram_post with container_id within 24 hours, and check get_account's can_publish_posts. It also states a precondition and what to do when it is not met ("say so and do not insist"). This is when/when-not/alternative guidance in full.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description reinforces this with 'Works without publishing turned on, and changes nothing on Instagram' and adds a return behavior (images come back small, `adjusted_to` signals a crop) that annotations do not cover. No output schema exists, so this output hint is valuable, though more detail on the response shape would help.

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

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

Front-loads the core purpose, then layers in the check/retry workflow and the side-effect guarantee. Every sentence is useful, though the parenthetical enum list and backticked field names add minor verbosity. Efficient overall.

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

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

With no output schema, the description carries the return-value burden and does so partially by disclosing small preview images and the `adjusted_to` crop signal. Combined with annotations covering the non-mutating profile and a fully documented schema, it is sufficient for correct invocation, though the exact return shape remains slightly ambiguous.

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 schema already documents all five parameters thoroughly, including the `fit` enum values. The description references `fit` options and `adjusted_to` but adds little syntax or meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb (preview) and resource (Instagram post), and clarifies the scope: it shows images as Instagram will crop/pad them before the post is prepared. It explicitly distinguishes itself from the sibling prepare_instagram_post by naming it. An agent can tell exactly what this tool does versus adjacent tools.

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

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

Explicitly says when to use it (before preparing the post), what to check (nothing important cut off), and what to do if cropped (try another `fit`, then pass the kept value to prepare_instagram_post). The alternative path is named with the condition that selects it.

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

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

Annotations are minimal (readOnlyHint false, destructiveHint false, openWorldHint false) and do not disclose access behavior. The description adds real behavioral context: the link is private, expires in about an hour, and requires the recipient to be signed in with their Saypage account. That is useful beyond the annotations, though it omits what happens on expiry or reuse.

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

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

Two short sentences, front-loaded with the key artifact (the private link) and its constraint (one hour). Minor awkwardness in the colon clause, but no padding.

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?

An output schema exists, so return-value detail is not required. The description covers the two things an agent most needs (privacy/access and the ~1 hour validity), making it adequate for a single-parameter tool.

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

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

Schema description coverage is 100% with a single trivial page_id parameter, so the schema already carries the meaning. The description adds no syntax or format guidance for page_id; 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 communicates that this tool produces a private preview link for a page draft, which distinguishes it from publish_page and get_page. The phrasing is slightly indirect ('A private link to the draft') — it never explicitly says the tool generates/returns the link — but an agent can infer the purpose.

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

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

It gives one usage instruction ('Share it with the user'), but no when-to-use vs. when-not context and no explicit alternative among siblings such as publish_page or get_page. Usage is implied rather than guided.

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 openWorldHint=true, but the description goes well beyond them: it discloses irreversibility (Saypage cannot delete a published post; the user must use the Instagram app), a rate limit (`publishing_quota`), and a retry hazard. That 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?

Short and front-loaded: the action and visibility come first, then safety caveats. The colon-led clause 'Ask the user first, with the final caption:' is slightly awkward but every sentence carries a distinct rule.

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

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

For an irreversible, externally-visible write with an output schema (so return values need no explanation), the description covers the missing pieces: reversibility, quota, and retry safety. Nothing an agent needs before invoking this tool is absent.

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 fully described in the schema ('From get_account', 'container_id from prepare_instagram_post'). The description mentions the prepare result only in passing (via publishing_quota) and adds no new parameter-level 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 (publish) and resource (a prepared Instagram post) and adds the scope 'visible to all their followers'. The emphasis on 'prepared' implicitly distinguishes it from prepare_instagram_post and preview_instagram_post, though it does not explicitly name the sibling publish_instagram_video it might be confused with.

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 sequencing ('ask the user first, with the final caption') and an explicit alternative action on failure ('never retry after an error without checking list_instagram_posts: the post may be live'). This is textbook 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?

Adds substantial behavior beyond the annotations: the publish is irreversible and unstoppable ('it cannot be stopped; only the user can delete it, in Instagram'), Saypage deletes its copy after processing, Instagram latency is 3 s to 15 min, and size limits (300 MB max, story 60 s/100 MB). This richly complements destructiveHint/openWorldHint rather than repeating them.

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

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

Front-loads the core action and the 'ask the user first' safety note, then layers timing, limits, and prerequisites. The telegraphic phrasing ('Saypage publishes it once Instagram has processed it') is dense but each sentence carries distinct, useful 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?

Given an output schema exists, the description needn't explain return values, and it still covers irreversibility, processing time, size constraints, the account prerequisite, and the list_videos follow-up. Nothing an agent needs to call this destructive publish 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%, so the schema already documents all 9 parameters, including the kind/trial/caption semantics and the story exclusion note. The description reinforces that the caption must be final and user-approved, but adds little 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+resource+scope: publishing an already-uploaded video to Instagram as either a Reel or a story. The 'video' framing distinguishes it from the image-oriented siblings (publish_instagram_post, prepare_instagram_post), and the Reel/story options map directly to the kind enum.

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

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

Gives a clear precondition (ask the user first with the final caption) and a gating requirement (publishing must be on via can_publish_posts, and if off, say so and don't insist). It doesn't explicitly route to alternative siblings like preview_instagram_post, so it falls 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?

Goes well beyond the annotations (which only flag it as non-readonly, destructive, and open-world) by disclosing quota behavior ('free plan publishes one page, 10 times a month'), the prerequisite Instagram connection, the asynchronous check delay, and the full outcome state machine including the review_state transition and how to recover from a rejection.

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 user-consent requirement, then constraints, then the outcome states. Every sentence carries information, though the outcome paragraph is dense and could be marginally tighter.

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?

An output schema exists, so return values need not be re-explained, yet the description still clarifies the `outcome` enum semantics and required follow-up actions. Combined with the quota and prerequisite notes, an agent has everything needed to invoke and interpret the call.

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

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

Schema coverage is 100% and the schema already documents both page_id and base_updated_at, so the baseline is 3. The description alludes to reviewing a draft before publishing but adds no format or conflict-handling detail beyond the schema's own 'detect conflicts' note.

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

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

States a specific verb and resource ('Publish the draft on the user's site') with clear scope, and is easily distinguished from siblings like unpublish_page and preview_page. An agent knows exactly what action is being taken 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 preconditions and workflow: ask the user first, requires a connected Instagram account and an eligible plan. It also routes the agent onward ('call get_page in a minute') when the check is pending. It does not explicitly contrast against preview_page or unpublish_page, 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 only declare readOnlyHint=false, destructiveHint=true, openWorldHint=true. The description adds substantive behavior beyond that: the reply is publicly visible, human approval is required, replies-to-replies are re-parented under the top-level comment, hidden comments are ineligible, and burst/identical replies trigger spam detection.

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

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

Four short sentences, front-loaded with what the tool does, each carrying a distinct constraint (approval, nesting, eligibility, pacing). No filler or repetition of the schema.

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

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

An output schema exists, so return values need not be described. For a mutating, open-world tool the description covers safety (user approval), eligibility, side effects, and rate-limit risk, leaving nothing an agent needs before calling 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 description coverage is 100%, so account_id, comment_id, and message are already documented (including the 1-2200 length bounds and 'in the commenter's language'). The description adds no parameter-level syntax or format detail, 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 (Reply) and resource (Instagram comment) plus the scope qualifier 'publicly ... as the user's account', which separates it from hide_instagram_comment and delete_instagram_comment. It never names a sibling tool, so the differentiation is inferred rather than explicit.

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

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

Gives explicit when/when-not conditions: show the user replies and get approval first unless pre-authorized, only top-level comments accept replies, and hidden comments cannot be answered. An agent has actionable routing and eligibility rules.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the agent knows this creates a link rather than a destructive write. The description usefully adds the manual browser flow and the post-upload handoff, but says nothing about link expiry, one-time use, or auth requirements for a tool whose whole output is a capability 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?

Two short sentences, front-loaded with what the tool returns, then the follow-up workflow. Some phrasing is awkward ('for chat apps without a shell') but nothing is wasted.

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

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

An output schema exists, so return values need not be described. For a zero-parameter tool, the description covers what it produces and what to do next, which is everything the agent needs before invoking 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?

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter surface the description needs to compensate for, and it correctly refrains from inventing inputs.

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 the concrete artifact returned (a link the user uploads photos/video through from a browser) and the narrow scenario it serves (chat apps without a shell). It is clearly distinguishable from the list/confirm tools, though it never contrasts itself with the obvious siblings start_image_upload / start_video_upload, which also initiate uploads.

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 qualifying condition (chat apps without a shell, browser-based) and a follow-up sequence (after upload, call list_images or list_videos). However, it never says when to prefer this over start_image_upload / start_video_upload, which are the sibling tools an agent would otherwise reach for, so the selection guidance is only implied.

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

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds substantive behavior beyond them, including the method-dependent transport (PUT raw body vs POST multipart with upload_fields plus file) and the expiry constraint ('Do it within expires_in_seconds'). It does not say what happens on expiry or on failure, so it falls short of fully disclosing edge 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?

The description is information-dense and every sentence delivers actionable detail, with two concrete curl examples that remove ambiguity about the two upload methods. It is slightly front-loads jargon (`upload_method`, `upload_headers`, `upload_fields`) before those names are grounded, requiring one read-through, but there is no filler.

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

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

For a two-step flow with an output schema, the description covers the essential path: initiate, upload within the expiry window, then confirm. Expiry/failure handling and quota or auth implications are not addressed, but nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so filename, content_type and size_bytes are already documented in the schema and the description adds no meaning to them. The terms it does illuminate (upload_url, upload_headers, upload_fields, expires_in_seconds) are outputs, not inputs, 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 opening clause ('upload a local image directly') gives a rough verb+resource, but the tool itself only initiates an upload session, and the description never states that it returns an upload URL, headers and fields for a subsequent PUT/POST. It also does not distinguish itself from start_video_upload or differentiate from the separate confirm step beyond naming it at the end.

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 scopes the audience ('For assistants that can run shell commands') and prescribes the follow-on action ('then call confirm_image_upload'), giving a clear sequencing context. It stops short of naming alternatives (e.g. start_video_upload for video, request_upload_link) or stating when this tool should not be used.

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 a lot beyond the annotations: upload must complete within expires_in_seconds, the video is only ever published on Instagram and never used in a page, and Saypage deletes an unpublished one at video_expires_at (an hour). It also spells out the exact transfer mechanics (PUT with upload_headers or multipart POST with upload_fields).

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

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

Front-loads the primary instruction and the chat-app alternative in the first two lines, then the mechanical steps. Every sentence carries actionable information despite the slightly fragmented line breaks.

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 the full lifecycle (initiate, transfer, confirm, expiry/cleanup) for a mutation tool, and an output schema exists so return values need no explanation. Nothing an agent needs in order to call 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?

Schema description coverage is 100%, so filename/content_type/size_bytes are already documented, and the description does not add meaning to them. Its upload_headers/upload_fields guidance concerns the upload handshake rather than the three declared parameters.

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

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

States a specific verb+resource (upload a local video) and scopes it to a Reel or video story. It distinguishes itself from request_upload_link and start_image_upload by naming both, so an agent can route correctly without opening 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 splits the audience: assistants that can run shell commands use this tool, chat apps use request_upload_link. It also names the follow-up step (confirm_video_upload) and the time window, leaving nothing to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds genuinely new context: the draft survives the operation, the call requires user confirmation, and it fails while an automation depends on the page. It stops short of covering downstream/external effects implied by openWorldHint (e.g., whether the live URL or automatic sends are affected).

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 the confirmation requirement, then the failure mode. The final clause 'point it elsewhere or remove its button (update_automation), or delete it, first' stacks alternatives awkwardly and leaves 'it' slightly ambiguous, costing 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?

Return values are covered by the output schema, and the description supplies purpose, confirmation duty, and the blocking precondition. The only gap is the ambiguous referent in the remediation sentence, which an agent must parse to act 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?

Single parameter with 100% schema description coverage, so the schema carries the definition. The description adds no syntax or format detail about page_id; baseline 3 applies.

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

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

States a specific verb+resource ('take a page offline') and immediately distinguishes itself from delete_page by noting the draft is kept. An agent can tell this apart from publish_page and delete_page without opening any schema.

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

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

Explicitly instructs 'Ask the user first' and names the precise condition under which the call is refused (an automation sends the page or has a button opening it), then routes to concrete alternatives: update_automation to relocate/remove the button, or deletion. This is when/when-not plus alternatives, all present.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, and the description adds real behavioral context on top: partial semantics (omitted fields retained), that live automations keep running and the next comment receives the change, a rate limit (once every few seconds), and the anti-pattern of deleting and recreating. No statement contradicts the destructive annotation; it clarifies that history and stats survive.

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

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

Front-loads the core update semantics in the first sentence and stays on-task, but a few sentences drift into soft product advice ("consider asking them, or offering drafts they can edit"). Slightly longer than needed for an agent-facing spec.

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?

An output schema exists, so return values need no explanation. For a 15-parameter destructive mutation the description covers partial-update behavior, rate limiting, live-state effects, and the safe alternative to delete/recreate — everything an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so parameter meaning is already well documented and the baseline is 3. The description still adds cross-field semantics the schema cannot express: omitted fields are kept, the field set mirrors create_automation, and provider_media_id is a move-with-history operation rather than a plain reference.

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

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

States a specific verb (Change) and resource (an automation), enumerates the mutable facets (post, link, keyword, messages, buttons), and adds the partial-update rule (omitted fields are kept) that distinguishes it from create_automation/delete_automation. An agent can tell exactly what this does without opening the schema.

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

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

Explicitly routes away from the wrong siblings: to move an automation to another post, use provider_media_id rather than delete_automation + create_automation, with the reason given (history and stats are preserved). It also states when to batch changes (one call, because of the update rate) and how to handle message rewording.

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 destructiveHint=true and readOnlyHint=false, and the description usefully narrows that destructiveness by clarifying the live page is untouched until publish. It also discloses a rate limit ('only be updated once every few seconds') and the shell upload workaround, adding real context beyond the annotations. It does not explain the conflict-detection role of base_updated_at.

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

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

Three sentences, zero filler, front-loaded with the core action before the supporting caveats about live state, rate limits, and shell uploads.

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 the draft/live distinction, rate limiting, and upload mode for a 3-param mutation tool, and an output schema exists so return values need not be explained. Minor gap: no mention of the concurrency/conflict semantics tied to base_updated_at, though the schema documents 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, but the description adds genuine meaning for html ('omit html to upload the file, as with create_page'), which the schema does not convey. base_updated_at conflict behavior 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?

States a specific verb and resource ('Replace a page's draft') and immediately disambiguates scope by noting the live page is unaffected until publish_page. An agent can distinguish this from publish_page and create_page 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?

Tells the agent when this applies (draft edits, not live changes) and routes to publish_page for publishing, plus names create_page for the shell-upload pattern. It stops short of explicit when-not-to-use conditions, but the context is clear.

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