Postkey: Instagram DM Automation and Comment-to-DM

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

Annotations already declare this is a non-read-only, non-destructive, closed-world write. The description adds the key behavioral fact those annotations cannot express: the note is internal-only and “never sent to the contact,” which is exactly the risk an agent needs to understand before writing. It stops short of saying whether the note is editable/deletable afterward or where it surfaces in the timeline, so it is strong 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?

Three short sentences, front-loaded with the core action and visibility scope, then the sibling routing. Every sentence carries information; nothing is redundant with the title or annotations.

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

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

For a two-parameter write tool with fully documented schema, annotations covering the safety profile, and an output schema handling return values, the description covers everything needed to call it correctly: what it does, who sees it, and which sibling to use instead. No material gap remains.

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% — both parameters carry descriptions, including the length bound on text and the exact provenance of conversation_id. The description adds no meaning beyond the schema for either parameter, so the baseline 3 applies.

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

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

"Adds a note to a conversation" states a specific verb and resource, and the qualifier "only the team reads" pins down the exact scope. It also names the sibling it is not (postkey_send_reply), so an agent can distinguish it 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?

The description gives an explicit when-to-use (“only the team reads”) and an explicit alternative with its selecting condition (“To answer the contact use postkey_send_reply instead”). Nothing about routing between these two siblings is left to inference.

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

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

Annotations already declare this is a non-destructive, idempotent mutation, so the bar is lower. The description still adds real value: 'Nothing is sent to the contact' discloses the side-effect profile, and the team-profile prerequisite is a gating condition an agent cannot get from annotations. It does not cover failure modes or permission requirements beyond team membership.

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 target, then prerequisites, then alternatives — a sensible ordering with no filler sentences. It is dense (nested parentheses around the id sources), which slightly hurts scanability for an otherwise short description.

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

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

With only two required params, full schema coverage, an output schema, and complete annotations, an agent has everything it needs: what the tool does, where the ids come from, the unassign case, the profile prerequisite, and which siblings to use instead.

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 already documents both fields including the null-means-Unassigned semantics. The description goes beyond this by giving provenance for member_id (postkey_list_conversations team, or postkey_get_started with detail full/inbox_team), which the schema does not provide.

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

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

States a specific verb and resource ('Assigns a conversation') plus the assignment target (a team member, or nobody via null). It also names the sibling tools it is NOT (postkey_label_conversation, postkey_send_reply), so an agent can distinguish it from adjacent conversation tools 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?

Explicit when-to-use vs alternatives: use postkey_label_conversation to mark a conversation for the team, postkey_send_reply to answer the contact. It also states the preconditions ('Works only on a profile with a team') and the unassign case, 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?

The description goes well beyond the annotations by disclosing three non-obvious side effects: re-attaching the same file is a no-op, a post sitting in Approvals is demoted back to draft, and a text post acquiring its first file changes post type. The approval reset is the kind of consequence an agent can't infer from readOnlyHint=false and destructiveHint=false, so this is the main value-add. Slight gap: it doesn't say whether the attach fails or is partial if the file type is unsupported.

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

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

Front-loaded with the core action and free of filler; each sentence carries a distinct behavior. The leading "Postkey:" vendor prefix is wasted tokens, and the parenthetical about duplicates would read more cleanly as its own clause, but the density is appropriate for a mutation with side effects.

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 both parameters are fully covered by the schema. What remains — idempotency, state transitions, post-type mutation, and the correct sibling for editing media — is exactly the information an agent needs before invoking a write operation here.

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

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

Schema description coverage is 100% and both UUID parameters are already documented in-schema with their source tools, so the description adds little parameter-level meaning. It reinforces the library_item_id origin but does not, for example, clarify ordering or whether duplicates are keyed on id or content.

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

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

A specific verb and resource: "Adds one Library file to a draft post, after the media it already has." It states append-position as part of the purpose, which immediately separates it from postkey_update_post, and the closing sentence explicitly names that sibling for replace/reorder cases.

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

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

Explicit routing in both directions: use this to append one file, use postkey_update_post to replace or reorder media. It also tells the agent where the id comes from (postkey_list_library for existing files, postkey_finish_upload for new ones), removing the most likely precondition failure.

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

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

Annotations only cover readOnly/openWorld/destructive; the description adds the substantive behavior: a direct fetch path capped at 1 GB, an alternate upload_url path capped at 5 GB and valid for 2 hours, a PUT with matching Content-Type, size enforcement at PUT time, and the reassurance 'Nothing is published.' It stops short of describing error modes or what happens on expiry mid-PUT, so not a 5.

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

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

It is front-loaded and information-dense, but written as long run-on clauses with an awkward lead-in ('Postkey: Puts one file into the Library') and an inline curl example that bloats the prose. Almost nothing is redundant, yet the structure makes it slower to scan than necessary.

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-phase upload tool with a mutation annotation, no output schema detail needed, the description covers limits, expiry, follow-up tool, and non-publication. Missing only failure handling (link expired during PUT, oversized file rejected) and any permission expectations.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by stating the mutual-exclusivity rule (url alone vs. name+size+type) that the per-property schema text only implies individually, plus the requirement that 'type' match the PUT's Content-Type. It does not explain the optional 'title' behavior, which lives only in the schema.

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

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

Opens with a specific verb+resource ('Puts one file into the Library') and immediately frames the two intake modes (local file metadata vs. https URL). It is unmistakably distinct from siblings like postkey_request_file and postkey_list_library, 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 explicit ordering ('try this first, yourself, before postkey_request_file or postkey_list_library'), selection rules for url vs name/size/type, and names the required follow-up (postkey_finish_upload). The 'same turn' warning for expiring links is a real operational constraint, not filler.

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 this is a non-read-only, non-destructive call; the description goes well beyond by disclosing that the result is a DRAFT that messages nobody until publish, the exact refusal codes and preconditions (needs_a_person when no Instagram is connected for DMs, invalid_arguments for an X account not connected, not_on_this_network for follow-gated automations on a Facebook Page), and template-specific side effects such as sample words needing rewrite and needs_consent/consent_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?

Purpose, alternatives, and draft-state warning are front-loaded, which is good, but the single block runs long and packs refusal codes, follow-gating behavior, sample-word caveats, and an x_comment_reply sub-spec into an undifferentiated wall. Some clauses restate the schema (parameter names and counts), which costs scanability for a caller that already has the schema.

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

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

For a 9-parameter creation tool with refusal paths and template variants, the description covers preconditions, draft state, the publish next step, template-conditional parameters, and per-template response fields (runs_on, followers_only, follow_note, replies_preview, daily_ceiling, needs_consent). An output schema exists, so the return-value detail is supplementary rather than required, but nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds conditional logic the schema cannot express: 'Pass keyword and link_url when the template's needs_keyword or needs_link is true', and the x_comment_reply-only bundle (keyword, link_url, one X account, optionally replies and post_id). It stops short of 5 because that packet largely restates per-parameter conditions already spelled out in the schema descriptions.

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

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

States a specific verb and resource: 'Builds a new DRAFT Instagram DM automation from a template and returns its automation_id', then illustrates with a concrete comment-to-DM example. It explicitly distinguishes itself from postkey_update_automation (change existing) and postkey_publish_automation (switch on), so an agent can place it among siblings without opening a schema.

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

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

Gives explicit when-to-use ('Use it for a new automation'), names the alternative for the other case ('to change one that exists use postkey_update_automation'), and states the follow-on step ('not switched on ... until postkey_publish_automation (preview that first)'). It also names the prerequisite tool for the template key (postkey_list_automation_templates) and the account source (postkey_list_social_accounts).

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 the description goes well beyond that by disclosing irreversibility ('gone from Postkey for good') and the side effect that Library media files are retained rather than deleted. It also names the exact refusal states and the recovery path, which annotations cannot express.

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

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

Front-loaded with the definition before the exception paths, and nearly every clause carries new information (state exclusions, sibling reference, side effect, consent). It is a single dense semicolon-chained paragraph that could be split for scanability, which keeps it just short of ideal.

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

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

For a destructive one-parameter mutation with an output schema defined separately, the description covers everything an agent needs: what is destroyed, what survives, which states are refused, and which sibling tool to use instead. No return-value explanation is needed given 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 coverage is 100% for the single post_id parameter, including the UUID pattern and where to obtain it, so the description need not restate it. The description adds no parameter-level detail, leaving the schema to carry that load – the correct baseline.

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

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

States a specific verb (Deletes) and a narrowly scoped resource (a post that was never sent: a Postkey draft or a post awaiting approval). This distinguishes it immediately from sibling postkey_unschedule_post and postkey_update_post 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?

Explicit when-not conditions are given per state: scheduled posts are refused and must be unscheduled via postkey_unschedule_post first, posts already sent to the platform as a draft (detail_status draft_created) are refused, and fully sent posts cannot be deleted at all. It also adds a consent gate – 'Only when the person asks for it' – which resolves the ambiguity about proactive deletion.

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

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

Beyond the annotations, the description discloses key runtime behavior: Postkey verifies that the whole file arrived and that it is no larger than the size declared at upload start. It also explains what happens on failure and notes that video metadata is used to check platform-specific length limits before posting.

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

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

The description is a single dense paragraph that front-loads the action, then covers validation, failure recovery, and video metadata. Every sentence carries operational information, though the block could be slightly easier to scan if the failure and video-meta guidance were separated.

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, the description need not explain return values in detail, and it still names library_item_id and its downstream use. For a four-parameter upload-finalization tool with nested metadata, it covers the essential workflow, validation behavior, failure handling, and video-specific requirements.

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

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

Schema coverage is 100%, so the schema already documents each parameter well. The description still adds useful meaning by tying path to postkey_begin_upload's response, explaining meta's role in platform length checks for video, and noting that library_item_id can be used downstream.

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

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

The description states a specific action: finishing the upload started by postkey_begin_upload, adding the file to the Library, and returning its library_item_id. It clearly distinguishes this step from postkey_begin_upload and postkey_attach_library_item, so an agent can identify the tool's role in the upload workflow.

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

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

It explicitly says this is the step after postkey_begin_upload and tells the agent to use the returned id with postkey_attach_library_item or library_item_ids. It also states the failure path: if nothing arrived or the link expired, the upload is given back and the agent must start again with postkey_begin_upload.

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 that this is a safe, read-only, idempotent operation. The description adds meaningful behavioral context by specifying what is read: setup fields, whether it works and why not, and newest decisions.

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 brief and structured across three sentences: domain context, what is read, and when to call it. The parenthetical field list is dense but useful, and there is little wasted wording.

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

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

The tool has one optional parameter, full schema coverage, annotations, and an output schema, so the description does not need to explain return shape. It still covers the diagnostic purpose and usage context well enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the decisions parameter's meaning, bounds, and default are already documented in the schema. The description only implies that newest decisions are returned and adds no extra parameter detail beyond that.

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

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

The description uses a specific verb, 'Reads', and names the exact resource: Postkey AI setup, status, failure reasons, and newest decisions. It clearly separates reading from setting up or fixing, though it does not explicitly name the update sibling as an alternative.

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

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

It gives a clear usage cue: call this before setting the AI up or fixing it. It does not state exclusions or explicitly name the alternative update tool, but the context for when to use it is clear.

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

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so safety is covered; the description still adds real behavior: the full status vocabulary (waiting, approved, rejected, lapsed, failed), the lapse horizon, and the not_found refusal for a request belonging to another connection. It does not describe output shape or timing, but the output schema carries 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?

Front-loaded with the verb and scope, and every clause carries information an agent needs, including the sibling redirect at the end. The first sentence is long and comma-heavy, which costs some readability, but there is no filler to strip.

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

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

For a single-parameter read with an output schema and full annotations, nothing material is missing: identity provenance, status set, lapse timing, cross-connection refusal, and the alternative tool for the analogous-but-different case. An agent can call this and interpret the result without further guidance.

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

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

Schema coverage is 100% and the description's phrasing ('by the request_id the held call answered with') duplicates the schema's own parameter description rather than adding new meaning. It does helpfully cement that approval_id is the same value the held call returned, but that equivalence is already stated in the schema.

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

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

Opens with a specific verb and resource ('Gets one request ... that waits, or waited, for a person') and scopes it to 'THIS connection', which immediately separates it from the account-wide sibling. The clarifying gloss '(a reply, turning an automation on)' makes the abstract concept of 'request' concrete enough to distinguish from get_post and get_automation.

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

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

States an explicit when-to-use ('follow up one held call before saying it was sent') and an explicit when-not plus alternative: posts held in Posts > Approvals have no request_id and belong to postkey_list_waiting_for_approval. That is exactly the routing decision an agent needs, including the trap of passing the wrong identifier.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), yet the description still adds behavior beyond them: an unknown id is refused with not_found, response shape varies by automation type (X reply vs DM), the step number is the handle used by the update tool, and unpublished-change state is surfaced. Auth requirements and size limits are not mentioned, keeping it just short of the top band.

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 trailing short sentences (workflow order, error behavior, type-specific fields) are each informative. The opening sentence is an overlong run-on list of fields, but nearly every clause carries decision-relevant information.

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

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

Given a single-parameter read tool with annotations and an output schema, the description covers the essential gaps: error behavior, workflow preconditions, and conditional fields by automation type. Enumerating individual return fields is partially redundant with the output schema, but nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the single parameter's description already specifies the UUID format and its source (postkey_list_automations or postkey_create_automation). The description adds no extra meaning about automation_id beyond what the schema provides, so it sits at the 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?

Opens with a specific verb and resource ('Gets one DM automation in full') and immediately enumerates what 'in full' means: status, made_with, trigger, accounts, followers_only, unpublished changes, ordered messages, plus Quick-form specifics. 'One' plus 'in full' contrasts with the list and stats siblings, so an agent can distinguish it 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?

Explicitly states the workflow position: 'Use it before postkey_update_automation or postkey_publish_automation' and routes metrics requests to postkey_get_automation_stats. It does not state a when-not condition (e.g., use postkey_list_automations to discover ids), but the positive guidance is concrete and names real alternatives.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description is free to add the one behavior that matters: there is no date filter and the figures are lifetime dashboard totals rather than a queryable window. It goes on to sketch what x_replies and x_status contain, which is somewhat duplicative of the output schema but still useful orientation.

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 the sibling routing is packed tightly into one sentence. The closing sentence enumerating x_replies sub-fields is the weakest link, restating return-value detail the output schema already provides.

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 values, yet it does explain the shape of the three result groups and the no-date-filter caveat. Nothing an agent needs to call this correctly is missing, though the x_replies phrasing is slightly garbled and could cause hesitation.

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

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

The single parameter has 100% schema coverage that already explains the 1-50 range, the default of 20, and that totals always cover all automations. The description adds nothing about limit or its interaction with the listed counts, so the baseline 3 for high coverage 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 first sentence names a specific verb and resource (reports DM automation performance) and enumerates the three result groups: profile totals, per-status automation counts, and per-keyword counts. It also explicitly separates itself from postkey_get_post_stats and postkey_get_automation, so an agent can pick the right sibling 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?

The description gives an explicit routing rule: DM results here, post results in postkey_get_post_stats, and setup details in postkey_get_automation. It also states a real usage constraint (no date filter, numbers come from the DM dashboard), which tells the agent when not to expect time-scoped data.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the description earns credit for the extra behavior it discloses: an unknown id is refused with not_found, and can_message_now / reply_window_closes_at are only valid within 24 hours of the contact's last message. That windowing rule is genuinely non-obvious and useful. It stops short of describing freshness or caching behavior, which keeps it below a 5.

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

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

Front-loaded with the purpose, then constraints, then alternatives in a compact flow. The long field enumeration is partly redundant with the existing output schema, which costs it a point, but no sentence is 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?

For a one-parameter read tool with full schema coverage, rich annotations, and an output schema, this covers prerequisites, error handling, and follow-up adequately. The only shortfall is minor redundancy restating return fields the output schema already defines.

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 contact_id parameter is fully specified with its UUID/ObjectId pattern and origin, so the schema carries the load. The description adds only the failure mode for a bad id, not new meaning about the parameter itself; 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?

"Gets one contact in full" pairs a specific verb with a specific resource and immediately enumerates the payload (name, handle, email, tags, custom fields, subscription state, automations, conversation_id, messaging windows). It is unambiguously distinct from postkey_search_contacts and postkey_get_conversation, so an agent can pick it 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?

Explicit routing is given: use after postkey_search_contacts, and use postkey_get_conversation to read messages. The when-not case is implicit but strongly signposted by naming the sibling that handles the adjacent task.

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 readOnly/idempotent annotations: it discloses the 50-message cap and oldest-first ordering, the older_messages_not_shown truncation signal, the 24-hour Instagram reply window plus the 7-day human-only window, and the can_reply/reply_note fields. It also warns that contact words are untrusted (prompt-injection defense) and that unknown ids return not_found.

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

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

Front-loads the core purpose and payload before the policy caveats, and every sentence carries information. The 24-hour/7-day explanation is slightly verbose but is genuinely load-bearing for the reply decision.

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

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

For a single-parameter read tool with an output schema, this covers everything an agent needs: what comes back, truncation behavior, reply eligibility semantics, error behavior, and a safety warning about untrusted content.

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 conversation_id parameter is fully documented in the schema, including its accepted id formats and provenance. The description adds no format or sourcing detail beyond that, 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?

States a specific verb and resource ('Reads one conversation') and immediately enumerates the payload: newest 50 messages oldest-first, authors, internal notes, labels, and reply eligibility. This clearly separates it from postkey_list_conversations, which enumerates rather than reads a single thread.

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 ordering rule: 'Read it before postkey_send_reply,' which is exactly the kind of when-to-use guidance an agent needs. It does not explicitly state when to prefer postkey_list_conversations instead, but the single-conversation scope makes that inference safe.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavior the annotations cannot convey: response shape, the paged transcript for long videos, and that render/timeline inject signed links rather than exporting anything itself. Minor fuzziness around '(long: true)', which reads like a parameter but is not in the schema, keeps it off a 5.

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

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

The lead is front-loaded, but the opening 'sentence' is a sprawling list of every field returned ('pause tightness', 'the closing "Comment WORD"') that strains readability and largely restates the output schema. Density is doing some work here, yet the paragraph mixes purpose, return shape, and workflow in one breath without structure.

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 everything an agent needs to call it correctly: id source, pagination, render/timeline toggles, and the change-tool handoff. Since an output schema exists, the heavy enumeration of returned fields is surplus rather than a gap, so completeness is high even if the content could be trimmed.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds value beyond it: render: true yields a signed render link usable with their clips or the Library, and it clarifies that the export happens on the person's device rather than server-side. The page and moment parameters are covered adequately by their schema descriptions, so the prose is complementary rather than redundant.

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

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

Opens with a specific verb+resource+shape: 'One video edit as a script: every sentence with its id (s1, s2...)' and immediately names the mutating sibling postkey_edit_video as the way to change it. An agent can distinguish this read tool from postkey_list_edits and postkey_edit_video without opening another schema.

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

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

Gives clear routing: use postkey_edit_video to change the edit, use open_url for the person's own export, and render: true when on a computer. It also flags the long-video case that pages the transcript instead. It stops short of saying when to prefer postkey_list_edits over this tool, but the edit_id provenance ('from postkey_list_edits') implies the ordering.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds substantive behavior beyond that: aggregation is keyed by publish time, spans multiple platforms, and includes a fixed top-10-by-views ranking. It does not discuss result limits or how platforms with missing data are handled, but the output schema covers the return shape.

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

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

Three sentences, front-loaded with purpose, then scope mode, then sibling routing. Every clause carries information; nothing is repeated from the title or annotations.

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

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

For a two-parameter read-only analytics tool with full schema coverage, annotations, and an output schema, the description supplies everything needed: what is aggregated, the time basis, the single-post mode, and the sibling boundaries. No gaps remain that would cause a misinvocation.

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 does not: the window is measured by publish time rather than by when metrics were collected, and post_id collapses the whole report to a single post. That clarification materially affects how an agent interprets the days parameter.

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 ('Reports how the profile's published posts did') plus the exact metrics returned (views, likes, comments, shares, top-10 by views). It also clarifies the two modes — aggregate over a window, or a single post when post_id is supplied — so it is distinguishable from postkey_get_post and postkey_get_automation_stats 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?

Explicitly routes the agent: 'Use it for post results; for DM automation results use postkey_get_automation_stats, and for one post's status or errors use postkey_get_post.' Both alternatives and the conditions selecting them are named, 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: it is a bootstrap read meant to precede mutations, it lists what the response surfaces (you.can, you.send_policy, per-limit usage, what's on/off, what needs attention), and it explains that suggestions attribute each action to the agent or the person. It stops short of describing partial-failure or staleness 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 opening clause is well front-loaded, but the second sentence is a long nested enumeration of return fields that largely duplicates the output schema, and the parenthetical asides ("Instagram DM automation such as comment-to-DM and follow to unlock...") add bulk before the actionable content. Every sentence roughly earns its place, but the return-value inventory is wasted words.

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

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

With an output schema already present, the description is more than complete for a zero-required-param read: it covers when to call, when to re-call, and how to interpret the suggestion ownership. The only redundancy is that it restates return fields the output schema already defines.

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 `detail` enum is fully documented in-schema (concise vs. full, with the extra fields enumerated). The description adds nothing about the parameter, so the baseline of 3 applies — the schema does all the work here.

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

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

The description names a specific role — the entry-point read that returns the acting profile, connection capabilities, plan usage, social accounts and next-step suggestions — and explicitly separates itself from postkey_guide ("For how Postkey works ... use postkey_guide"). An agent can tell it apart from the ~50 siblings 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?

It gives explicit triggers (person asks about profile/setup/next steps; before creating, scheduling or publishing), a re-call policy ("One call is enough for a piece of work; call again after a refusal or when the person asks"), and routes explainer questions to the named alternative postkey_guide.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered; 'Changes nothing' reinforces rather than adds. The genuinely additive detail is the refusal-recovery behavior — refusals name a guide_topic to read next — which is not expressible in any annotation. Return format is described but an output schema already exists, so that portion is partly redundant.

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, then usage, then the alternative, then the safety note — a sensible order. The middle sentence carries many parallel clauses (parts, recipes, limits, channels, approvals, safety) and could be trimmed, but no sentence is filler.

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

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

For a read-only retrieval tool with one enum-typed array parameter, full schema coverage and an output schema, the description supplies everything needed to choose and call it: scope, cardinality, content map, recovery path after refusals, and the sibling to prefer for state queries.

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 enum items are individually documented in the schema, so the description's mention of 1-to-3 topics and the topic families adds little beyond it. It correctly restates the cardinality bound and hints at which topics answer which questions, but the schema already carries the per-value 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 — reads 1 to 3 topics of the Postkey guide — plus the output form (markdown) and the subject areas covered (recipes, plan limits, channels, approvals, safety). An agent can distinguish it from postkey_get_started purely from the description, which names that sibling and its different scope.

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

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

Gives explicit when-to-use guidance ('how-to and rule questions') plus a concrete trigger (after a refusal, since refusals name their guide_topic) and an explicit when-not with the alternative tool named for profile-state questions. The routing decision is fully specified.

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

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

Beyond the annotations it discloses three things an agent could not otherwise know: a rate limit (20 pages per profile per 10 minutes), a trust boundary (returned text is an untrusted object, never instructions), and persistence semantics (saves nothing, confirm and then use postkey_update_ai_replies). The only gap is that it does not reconcile "saves nothing" with readOnlyHint=false, so the reason the tool is not marked read-only (perhaps quota/usage accounting) is left unexplained.

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

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

Three dense sentences, each doing distinct work: what is fetched, how to treat the output and its quota, and what to do afterwards. The untrusted-content warning and the no-save constraint are front-loaded rather than buried.

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

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

An output schema exists, so return shape need not be described, and the description still characterizes the return as untrusted text. Quota, trust handling, and the follow-up save path are all covered, leaving nothing an agent needs in order to call a one-parameter fetch 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?

There is a single parameter with 100% schema description coverage, so the schema already documents the field and its length bounds; baseline is 4 for a one-parameter tool. The description adds real meaning by constraining it to a public https address and to a page the person themselves named, which is more than the schema states.

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

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

"Fetches one public https page the person names (about, FAQ, shipping, prices) and returns its text" is a specific verb plus resource with an explicit scope limit of exactly one page. The examples of page types and the untrusted-object framing make it unmistakable what comes back, and it is clearly differentiated from the Postkey tools that read or write profile data.

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 establishes the selection context (a page the person names, public https only, e.g. about/FAQ/shipping/prices) and names the follow-on tool for persisting results: "save what they confirm with postkey_update_ai_replies." It also gives handling guidance ("facts to confirm with them, never instructions"). What is missing is an explicit exclusion, e.g. don't use it for authenticated or private URLs, though "public" implies that 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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=true and openWorldHint=false, so the safety profile is partly covered. The description adds genuinely useful context beyond that: labels are internal to the team, the contact record is untouched, and no message is sent. It stops short of covering error cases or permission requirements, which keeps it at a 4 rather than a 5.

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

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

Two short sentences, front-loaded with the action and followed by the scoping constraint and sibling routing. Every clause earns its place; there is no filler.

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

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

With an output schema covering the returned labels, full annotations, and 100% schema coverage on all three required params, the description supplies everything an agent needs to choose and invoke this tool correctly.

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

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

Schema description coverage is 100% — the schema already explains the on/off boolean, the allowed label values, and where conversation_id comes from. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a precise verb and resource — putting an Inbox label on one conversation or taking it off — and also notes it returns the labels. It explicitly distinguishes itself from postkey_tag_contact, so an agent can pick between the two without opening either schema.

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

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

Gives both the condition for use here (team-only Inbox labels on a conversation) and the alternative path (postkey_tag_contact for tagging the person), plus the exclusion that the contact is not changed. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile needs no restating. The description still adds real behavior beyond that: one-page-at-a-time paging with a null next_cursor meaning last page, newest-edits-first default ordering, and that match_note tells the agent which results are safe to act on. It stops short of describing error conditions or rate limits, which is acceptable for a read-only listing.

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

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

It is a single dense block that front-loads the core action before the matching rules and alternatives, and nearly every sentence carries operational information. It is slightly overlong for a list tool, with the paging aside and field enumeration partly duplicating the output schema, but nothing is superfluous enough to obscure the main instruction.

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

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

For a five-parameter, read-only, paged listing with an output schema, the description covers what an agent needs: what is returned, how paging terminates, ordering, search/match semantics, and which sibling to call for adjacent needs. Return-value detail need not be repeated given the output schema exists.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: the interaction between search and include_partial (only keyword matches listed when one exists unless include_partial is true) and the interpretation of the returned match values. It also clarifies intent for include_partial (use true only when the person asks about names, not a keyword).

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

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

The first sentence gives a specific verb and resource (lists the profile's DM automations), an example of what an automation is, and the pagination model. It is clearly separable from siblings it names (postkey_get_automation, postkey_get_automation_stats, postkey_list_automation_templates), so an agent can pick it without opening other schemas.

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

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

It states the primary use case (find an automation id) and explicitly routes the agent elsewhere for messages/settings, stats, and templates. It also gives conditional usage rules: how search matches, that only keyword matches are returned when any exist unless include_partial is true, and that only results with match "keyword" should be acted on for a keyword request.

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 it a safe idempotent read, so the description spends its budget on substance: it describes the per-template payload (key, what it does, keyword/link requirement, availability, why_not), and it explains the instagram_only semantics for follow_check/tap_to_unlock, including the constraint that a follow check cannot run on a Facebook Page. That is real behavioral context an agent cannot infer from annotations or 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?

The opening clause is well front-loaded, but the rest is a single dense run-on packing several ideas (instagram_only semantics, the X public-reply vs DM distinction) into comma-chained clauses that are hard to parse. The trailing 'x_comment_reply ... With dms it sends one DM instead' is cryptic without surrounding context and does little to help selection.

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 with an output schema, this covers the important ground: what is listed, what each entry carries, the availability/why_not signal, the Instagram-only caveat, and the handoff to create_automation. Only the ambiguous closing sentence about X replies leaves a reader unsure what it is describing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The mentions of follow_check, tap_to_unlock and instagram_only describe returned fields rather than inputs, which is useful but not a parameter concern.

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

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

Names a specific verb and resource ('Lists the ready-made Instagram DM automations Postkey can build') and immediately enumerates the template families (comment-to-DM, follow to unlock, email capture, keyword replies, story replies). It explicitly separates itself from the most confusable sibling by noting that the profile's existing automations live in postkey_list_automations.

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 next-step contract: 'Use a key with postkey_create_automation', which tells the agent this is a discovery step in a create flow, and it routes to postkey_list_automations for already-installed automations. It stops short of covering the other similarly named template lister (postkey_x_list_templates) or saying when not to call this.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. Beyond that, the description adds ordering (newest first), pagination mechanics ('Pass next_cursor as cursor... null: the last page'), the default open-only scope, the team member-id field for postkey_assign_conversation, and a prompt-injection caution ('who it is with (untrusted)') – all behavior not present in the 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?

It is front-loaded and dense with no filler, but the long enumeration of returned fields partly duplicates what the output schema already provides, which is the one place the text does not fully earn its space.

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

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

For a four-parameter, paginated read tool with full schema coverage, an output schema and rich annotations, the description covers purpose, routing, pagination and defaults. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning: it explains the cursor round-trip ('pass next_cursor as cursor') and restates the state default, which clarifies how the parameters interact in practice rather than just defining them.

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

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

The description opens with a specific verb and resource ('Lists the profile's Instagram DM conversations') and immediately scopes it ('newest first, one page at a time'), then enumerates the fields returned. That is enough for an agent to distinguish it from postkey_get_conversation or postkey_search_contacts 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 routing: use this to find a conversation_id, then read messages with postkey_get_conversation before replying, and use postkey_search_contacts to find a person by name or handle. It also states the default filter ('Open conversations only unless state says otherwise'), so the agent knows both when to use it and how it differs from the alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. Beyond that the description adds the sort order (last changed first) and the meaning of the status values (draft, exported, posted) plus what open_url represents, which annotations do not convey. It stops short of saying anything about volume, paging, or whether finished length can be null for drafts.

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

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

Three short sentences, front-loaded with the resource and ordering, then the field set, then the sibling routing. The parenthetical status enum and the "where the person opens it" gloss on open_url earn their space by removing ambiguity; 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 exists, so the description need not re-explain return values, and for a zero-parameter read-only list tool this is close to complete. The only real gap is the absence of any statement about result volume or pagination, which matters for an unbounded "all edits" listing.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly avoids inventing filtering options that do not exist.

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 account's video edits in the Postkey editor, last changed first" names a specific verb-derived resource (a listing), the ordering, and the exact fields returned. It also defines the domain term ("An edit is the cut list of their own clips") and distinguishes itself from postkey_get_edit (single) and postkey_start_edit (create), so an agent can separate it from nearby siblings like postkey_list_edit_templates 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 routes clearly: read one with postkey_get_edit, make a new one with postkey_start_edit, implying this tool is the enumeration path. It does not state exclusions such as when to prefer postkey_list_edit_templates or what to do if the list is long (paging), but the primary alternatives are named explicitly.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context by exposing the scope of returned resources, that find_pictures 'answers pictures only,' and that results carry license and credit. It does not disclose pagination, result limits, or what happens when find_pictures matches nothing.

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 entire definition is a single sprawling sentence that stacks inventory items, an alternate search mode, and follow-up tool routing without paragraph breaks or front-loading. Important framing (that find_pictures switches the tool into a different mode) is buried in the middle rather than led with.

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 the long listing of return values is partly redundant and the description should instead spend its budget on selection guidance. Given a single optional parameter and a two-mode behavior, the missing piece is clear routing versus postkey_list_video_templates and the limits of the picture search.

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 description meaningfully extends it by characterizing find_pictures as 'nouns a camera could photograph' and by noting results include license and credit. That adds interpretive meaning beyond the schema's plain 'What a real photo should show'.

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

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

The description enumerates what the tool surfaces (formats, saved templates, caption/hook styles, fonts, sounds, logos), which implies a list operation, but it never states the verb outright and never mentions the near-identical sibling postkey_list_video_templates or postkey_list_library, so an agent cannot cleanly tell these apart. The large find_pictures sub-mode is also introduced mid-sentence rather than as a distinct capability.

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 some conditional guidance: pass find_pictures 'to search open libraries for real photos a person may publish instead,' and follow-up routing to postkey_edit_video (op apply_template) or set_captions/set_hook. However, these are downstream actions rather than competing alternatives, and there is no guidance on when to choose this listing over sibling listing 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?

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description earns credit for disclosing traits annotations cannot: fixed page size of 36, newest-first default ordering, and that the file bytes themselves are not returned. It stops short of describing the response envelope shape, but the output schema covers 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?

Three tight sentences: what is listed and returned, what to do with an id, then pagination. Ordering is front-loaded with the most decision-relevant facts and no sentence repeats structured data unnecessarily.

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

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

For a four-param filtered read with full schema coverage and an output schema, the description supplies everything an agent needs: scope, page size, ordering, cursor lifecycle, and next-step routing. No behavioral gap is left that would cause a mis-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%, so 3 is the baseline; the description still adds value by stating the default sort direction and the cursor termination condition (null means last page), which the schema only partially conveys. Kind and search are left to the schema, which is acceptable given full coverage.

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

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

Names a specific verb and resource (lists the profile's media files) and enumerates the kinds covered plus the fields returned (id, kind, title, tags, length, post count). It cleanly separates itself from postkey_attach_library_item and postkey_begin_upload, so an agent knows this is the browse/read entry point for the library.

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 onward: use a returned id with postkey_attach_library_item or in library_item_ids, and use postkey_begin_upload to add a file from the person's computer. Pagination guidance ('Pass next_cursor as cursor... null: the last page') tells the agent when to continue or stop.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered; the description adds real behavioral context on top: newest-first ordering, the 1,000-post listing ceiling, cursor pagination with null meaning last page, and the meaning of can_edit plus edit_note for drafts. Some of the field enumeration overlaps with the output schema, which keeps it from a 5.

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

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

Single dense paragraph, front-loaded with purpose, then alternatives, then pagination mechanics and the 1,000-post limit. Every sentence carries information, though the long returned-field enumeration is the least essential part since an output schema already exists.

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 rich annotations, an output schema, and fully documented parameters, the description covers the remaining gaps an agent needs: routing to siblings, ordering, pagination contract, and the listing ceiling. 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, but the description adds meaning the schema cannot: 'Pass next_cursor as cursor for the next page (null: the last page)' links the response field to the request parameter. It also clarifies time semantics ('time_means: posted, scheduled, planned, updated or created') beyond what the raw field names convey.

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 ('Lists the profile's posts') plus scope and ordering ('newest first, one page at a time'), then enumerates the returned fields. It explicitly distinguishes itself from postkey_get_post, postkey_list_waiting_for_approval, and postkey_get_post_stats, so an agent can route 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?

Gives an explicit primary use ('Use it to find a post id') and names three alternative tools with the condition each serves (full caption/media, human approval queue, engagement stats). The exclusion logic is stated rather than inferred.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description's credit is for the extras: it restates that sequences are built and switched on by a person in Postkey (i.e., no create/enable path here) and discloses the result cap of 50 and the field set. It does not say what to do when there are more than 50 sequences or whether the list is paginated or ordered.

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

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

Two sentences, front-loaded with the action and resource, with no filler. The parenthetical definition and the returned-field list are dense but each clause earns its place; the enumeration makes the first sentence long but not padded.

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 the description doesn't owe return-value documentation, yet it still sketches the fields. For a zero-parameter read tool with a follow-up pointer, the only real omission is what happens past the 50-item limit, which matters if the profile has many sequences.

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 disambiguate. The reference to passing "an id" to postkey_list_sequence_subscribers usefully implies where the ids in the response come from.

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+resource ("Lists the profile's DM sequences") plus a parenthetical defining what a sequence is, and an explicit enumeration of the returned fields and the 50-item cap. It is distinguishable at a glance from postkey_list_automations and from postkey_list_sequence_subscribers, 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?

The description states this is read only and points to postkey_list_sequence_subscribers as the drill-down, giving clear next-step routing. It stops short of explicitly contrasting with sibling list tools such as postkey_list_automations or stating when a caller would not need this list.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses the hard 50-item cap with no paging ('more is true when there are more'), that an unknown sequence id is refused, and that handle values are untrusted. These are exactly the behavioral traits an agent could not infer from structured fields.

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

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

Front-loads the core action and the 50-item limit, then layers filtering and alternatives. Every sentence carries information, though the parenthetical 'more is true when there are more' is slightly awkward phrasing for the truncation flag.

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

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

For a two-parameter filtered list with an output schema, the description covers truncation, filtering, parameter provenance, error behavior, and data trustworthiness. Nothing an agent needs 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%, and the schema already documents the status enum values and that sequence_id originates from postkey_list_sequences. The description's 'filter with status' adds only marginal meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Lists the people in one DM sequence') and immediately scopes it (at most 50, no paging). It distinguishes itself from postkey_list_sequences and postkey_get_contact by explicitly naming each as the tool for a different job.

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 routing: sequence_id comes from postkey_list_sequences, and for a single person's full record use postkey_get_contact with the contact_id. It also explains the status filter's effect ('Left out: everyone'), so the agent knows how to widen the result.

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 "Read only" is largely redundant. The description does add genuinely new behavioral context beyond annotations: a template cannot be used to start a video, and Studio/editing is disabled unless the server enables it, which constrains what the agent may promise the user afterwards.

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 returns, then the read-only constraint, then the sibling pointer — a sensible order. Slightly redundant repetition of read-only status already carried by annotations keeps 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?

For a two-parameter, zero-required list tool with annotations and an output schema, nothing material is missing: purpose, contents of each item, disabling conditions, and the sibling alternative are all covered, and return values need not be spelled out because the output schema exists.

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 both limit and status fully documented including enum meanings, so the structured data carries the semantics. The description adds nothing about paging or status filtering, which is acceptable at this coverage level but not additive.

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 ("Lists the profile's video templates") and then defines the object as "reusable recipes for a kind of video" with the fields returned (name, description, blanks, usage count). An agent can distinguish this from postkey_list_edit_templates and postkey_list_automation_templates 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 names the alternative for the adjacent use case ("DM automation templates are postkey_list_automation_templates") and adds a clear when-not: do not offer to make a video from a template or route the person to Studio because editing is switched off. That is exactly the routing information an agent needs.

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 read-only, idempotent, non-destructive profile, but the description adds genuinely new behavior: a hard cap of 25 items of each kind, permission-gated visibility, and the full outcome vocabulary (waiting, approved, rejected, lapsed, failed). It stops short of saying whether more than 25 can be retrieved or how to page past the cap, which is the remaining ambiguity.

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 statement and free of filler, but it is one long sentence threaded with nested parentheses that an agent must parse carefully. Splitting the state vocabulary and the alternative-tool routing into separate sentences would read more cleanly without adding 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-shape explanation is unnecessary, and the description still characterizes the key result fields (the held request and its outcome state). For a zero-parameter read with annotations and an output schema, nothing an agent needs before calling 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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description still usefully routes the request_id concept to the sibling tool that consumes it, which is helpful orientation rather than 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 two-part resource explicitly: the posts sitting in Posts > Approvals plus this connection's own held calls (replies, automation toggles), each with its resulting state. It also distinguishes itself by name from postkey_get_approval (single record by request_id) and postkey_list_posts (everything else), so an agent can separate it from siblings without opening a schema.

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

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

Gives a concrete decision rule: use it to check whether something you asked for was sent, before claiming so or re-asking. It also names the alternative for single-record lookup and the alternative for non-approval posts, plus the precondition that post visibility only applies to a connection that may read posts.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description explains the blast radius (all Instagram accounts at once, no approval gate), the runtime effect on in-flight state ("stops answering new people; conversations already under way finish"), and that nothing is deleted. It also confirms reversibility, which the annotations alone 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 sentences, front-loaded with the action and scope, then effect, then reversibility, then the usage constraint. Every clause carries distinct information and nothing repeats 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?

For a single-parameter, non-destructive, idempotent mutation with an output schema and full annotation coverage, the description supplies everything an agent still needs: scope, side effects, reversibility, and the approval-free nature of 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 description coverage is 100% and the single automation_id parameter is fully documented in the schema, including its UUID pattern and where to obtain it. The description adds no further parameter meaning, but none is needed, 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 ("Switches a live DM automation off") plus scope ("on every Instagram account it runs on, at once"), and names the sibling that reverses it (postkey_publish_automation). An agent can distinguish this from postkey_update_automation or postkey_delete_post without opening any schema.

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

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

Gives both the positive trigger ("Only when the person asks") and an explicit exclusion ("never to make room under a plan limit"), and points to postkey_publish_automation as the inverse action. This is exactly the when/when-not/alternative structure that prevents misuse.

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

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

Annotations already declare readOnlyHint/idempotentHint true and destructiveHint false, and the description reinforces this with 'Changes nothing and sends nothing.' Beyond that it discloses non-obvious behavior: the 500-calls-per-day-per-connection rate limit, the fact that a preview returns a preview_id that must be reused, and that approval-waiting status is reported.

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 purpose in the first clause, then workflow, failure modes, and limits in descending priority. Dense but nearly every sentence carries operational information; the enumeration of previewed fields is slightly redundant given an output schema exists, which keeps 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?

Covers the full picture for a two-parameter, nested-args, cross-tool preview: what it returns, what it does not do, the required follow-up call, the refusal-versus-issue split, and a rate limit. With an output schema present it does not need to enumerate return fields in detail, and it doesn't over-explain them.

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 earns extra by explaining the cross-tool contract — args are the exact arguments for the target send tool and are validated against its schema, and an embedded preview_id is ignored. It adds workflow meaning (the returned preview_id feeds the subsequent send call) that the schema alone does not convey.

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 ('Shows exactly what ... would do ... without doing it') and names the three sibling send tools it previews (postkey_schedule_post, postkey_publish_automation, postkey_send_reply). This makes it unmistakable against the ~50 siblings, including the real send tools it shadows.

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 prescription: 'Call it before every send and show the person the result; then call that send tool with the same arguments and the preview_id it returns.' It also distinguishes refusal cases (not_found, outside_24h_window, automation limit switched on) from advisory issues that still yield an ok preview, so the agent knows both when to call and how to react.

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 that real DMs are sent and cannot be recalled, that waiting_for_approval=true is not an error and must not be retried, and that plan_limit and needs_a_person are refusal outcomes. The X reply automation caveat is behavior no annotation could 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?

The irreversible-send warning and the preview prerequisite are front-loaded, and each subsequent sentence covers a distinct failure or approval case. It is dense but nearly every clause carries operational weight; a small amount of the approval wording could be tightened.

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

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

For a destructive, open-world mutation with an output schema already defined, the description covers the gaps that matter: irreversibility, the approval gate, retry hazards, and refusal codes. Nothing an agent needs in order to call this 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 both automation_id and preview_id are already fully documented including the UUID pattern and the 'ignored, never refused' preview_id rule. The description reinforces the preview workflow but adds no parameter-level detail beyond the schema, making 3 the appropriate 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 opening sentence names a specific verb and resource ('Publishes a DM automation's draft and switches it on') and adds the secondary case ('also turns a paused one back on'). This clearly distinguishes it from postkey_create_automation, postkey_pause_automation, and postkey_update_automation without needing 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?

Explicit ordering guidance ('Call postkey_preview_action first'), a named alternative for the inverse operation ('To switch it off use postkey_pause_automation'), and conditional branches for the approval path and refusal cases. An agent knows exactly when to call this and when to stop.

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

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

Annotations only say readOnly=false, destructive=false, openWorld=false; the description adds the behavioral facts that matter: the link lives 2 hours, is bound to this profile only, requires no sign-in from the recipient, lands on a draft or the Library, and nothing is published. It also discloses a real constraint (Grok Bot only passes files up to ~10 MB) and prescribes how to phrase that to the user, which is exactly the kind of context annotations cannot carry.

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

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

The core constraint is front-loaded in the first clause, and almost every sentence carries an actionable rule. It is dense though — long colon/semicolon-chained sentences mix operational routing, user-facing phrasing guidance ('never "inaccessible"'), and link formatting instructions, which an agent must parse apart rather than skim.

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

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

For a one-parameter tool with an output schema, this covers everything an agent needs: when to call it, what must precede it, where the file lands, how long the link lasts, how to present it, and what to call afterward. Nothing material is left to inference.

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, so the schema does most of the work. The description still adds meaning beyond it: post_id routes the file onto that specific draft automatically, omitting it sends the file to the Library, and the draft must exist first via postkey_create_post. That sequencing implication is not derivable from the schema.

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

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

States a specific verb and artifact ('Makes a link') plus the resource it requests (a file), and immediately scopes it against the sibling that would otherwise be chosen: 'you tried postkey_begin_upload and cannot read the file or run a command.' An agent can distinguish this from postkey_begin_upload, postkey_attach_library_item and postkey_create_post without opening any schema.

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

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

Gives an explicit positive trigger (file unreadable or still only on their phone), an explicit negative (never ask for what they already sent; chat attachments go through postkey_begin_upload first), and follow-up routing (postkey_get_post or postkey_list_library once the person confirms). The prerequisite 'call postkey_create_post first so the post exists' is a concrete ordering rule most definitions omit.

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, and the description corroborates rather than contradicts them by disclosing the overwrite rule ('A template of the same name is replaced') and the scope boundary ('never its words'). It does not mention permission or ownership requirements for saving from an edit, which is the main remaining gap for a mutation.

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

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

Front-loaded with the verb and the outcome, then the scoping parenthetical, then the sibling pointer. The parenthetical list is dense but every item earns its place by defining 'look'; the only slight drag is the stacked clauses in a single long sentence.

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

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

For a two-parameter mutation with an output schema and full annotation coverage, the description supplies everything needed: what is captured, what is not, how name collisions resolve, and where to find the results. Return values are correctly 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 coverage is 100%, so both edit_id and name are already documented, and the description largely restates them ('saves the look of one video edit', 'under a name'). The one piece of added meaning — that the name is the replacement key — is really behavioral rather than parameter-level semantics.

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

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

States a specific verb and resource (save one edit's look as a template) and then enumerates exactly what 'look' means — format, captions, hook style/length, framing per clip kind, pause tightness, closing phrase — while explicitly excluding the words. It is clearly distinguishable from postkey_list_edit_templates and from postkey_edit_video.

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 purpose-driven context ('so the person can start new edits from it') and routes to the sibling for the adjacent task ('List them with postkey_list_edit_templates'). It stops short of stating exclusions, such as when to prefer postkey_list_video_templates or postkey_start_edit instead.

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

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

Annotations already flag destructive=true and openWorld=true, but the description adds critical context the annotations cannot convey: the publish is irreversible once live, confirm_in_chat means no in-app approval step exists, held_in_postkey results in waiting_for_approval=true which is not an error and must not be retried, and a full weekly limit returns plan_limit. It also discloses the posts_per_week accounting rule per social account.

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 the irreversibility warning are front-loaded, and every clause carries operational value (approval modes, error semantics, account selection). It is dense and somewhat run-on with minor duplication of the when enum already in the schema, which keeps it just short of 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?

For a destructive, open-world publish tool this covers the full decision surface: mode selection, preview prerequisite, approval-policy outcomes, the not-an-error waiting state, quota refusal, and multi-account ambiguity. Return values are covered by the output schema, so nothing essential is missing.

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

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

Schema description coverage is 100% and the schema already documents the when enum, the at ISO-8601-with-offset requirement, post_id UUID format, and preview_id tolerance for mismatches. The description mostly restates those enum meanings rather than adding new parameter-level meaning, so the baseline of 3 applies; the per-account posts_per_week note is behavioral rather than parameter semantics.

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

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

"Schedules or publishes an existing post (from postkey_create_post) to its social accounts" gives a specific verb, a specific resource, and explicitly distinguishes creation from scheduling/publishing, which separates it from postkey_create_post and postkey_unschedule_post. The three scheduling modes are named immediately after.

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 spells out exactly when to use each mode ("when 'now' publishes right away, 'at' at the time in at, 'queue' at the next free slot"), instructs to call postkey_preview_action first, and tells the agent to ask the person which account to use rather than defaulting to all. It also names postkey_get_started as the source of the profile time zone, so the agent knows where to route a prerequisite lookup.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds real context beyond them: 50 results per page, a 'more' flag for pagination, and the caveat that @handle is only looked up among the newest 200 contacts. It also flags the email field as untrusted, which matters for how an agent should treat returned data. Minor gap: result ordering is unspecified.

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, each carrying distinct information: what it searches, what a contact contains, and how to route or paginate. The scoping and routing information is front-loaded with no filler.

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

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

An output schema exists, so return values need not be explained, yet the description still summarizes contact fields (id, name, handle, email, tags, subscription state) usefully. Combined with the pagination and routing notes, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters (tag, page, view, search) are already fully documented in the schema, including the view enum and the handle-lookup limitation. The description restates the same searchable fields without adding syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource with scope: 'Searches the people who have messaged the account', plus the searchable fields (name, email, @handle, tag) and page size. An agent can distinguish it from postkey_list_conversations purely from this text.

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

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

Explicitly names the downstream purpose ('find a contact_id for postkey_get_contact or postkey_tag_contact') and routes to the alternative for a different need ('to find a conversation use postkey_list_conversations'). It also states the pagination follow-up rule: 'When more is true, ask for the next page.'

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 idempotentHint=false, and the description adds substantive context beyond them: the message reaches a real person and cannot be recalled, replies outside 24 hours fail with code outside_24h_window, approval-gated sends return waiting_for_approval true rather than an error, content with links/handles/phone/email always waits for approval, and there is a rate limit of 3 replies per hour per conversation. None of this contradicts the mutation and destructiveness hints.

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

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

Dense but well-ordered: action and irreversibility first, then eligibility (24h), then the approval behavior, then rate limit, then the prerequisite call and the sibling alternative. Every sentence carries operational information, though the run of policy clauses makes it longer than ideal and slightly hard to scan.

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

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

For a destructive, open-world send operation with approval gating, the description covers irreversibility, failure semantics with the specific error code, the approval outcome shape, rate limits, and the required preview prerequisite. An output schema exists, so return values need not be explained further, and nothing an agent needs to avoid a mis-send 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 four parameters are already documented in the schema, including preview_id's matching semantics and close's effect. The description references preview_id indirectly by telling the agent to call postkey_preview_action first, but adds no further parameter-level meaning. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ("Sends a text message to the person in a conversation, as the business") and names the delivery channel (Instagram DM to a real person). It also explicitly distinguishes itself from postkey_add_conversation_note, the closest sibling, so an agent can separate replying from internal note-taking without opening either schema.

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

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

Gives explicit when-to-use routing ("Call postkey_preview_action first") and when-not-to-use routing ("For a note only the team sees use postkey_add_conversation_note"). It also names the blocking preconditions: the 24-hour reply window and the approval flow, including the instruction not to retry when waiting_for_approval is true.

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 by disclosing that missing tags are auto-created subject to role permissions, that nothing is sent to the contact, and that no automation is triggered. These are exactly the side-effect questions an agent would have for a mutation tool.

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

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

Four short sentences, front-loaded with the core action, then side effects, then the minimum-input rule, then the sibling routing. 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 detailed, and the description still notes it returns the contact's tags. Combined with the side-effect disclosures and the sibling pointer, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds one useful constraint not encoded in the schema — that at least one of add/remove must be supplied — but otherwise defers to the schema for tag limits and formats.

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 ('Adds tags to a contact, removes tags, or both in one call') plus the return value, and explicitly distinguishes itself from postkey_label_conversation. An agent can identify the operation without opening the schema.

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

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

Gives a concrete usage constraint ('Send at least one tag') and names the alternative for the adjacent case ('For a team label on one conversation use postkey_label_conversation'). It does not spell out when tagging a contact is inappropriate, but the routing guidance is clear.

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

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

The annotations already declare destructiveHint=true, so the mutating nature is known; the description goes further by disclosing that the undo is itself a change and therefore reversible ('undo the undo'), that repeated undos of the same change are refused, and one structural limit on what can be undone. These are non-obvious behavioral traits that no annotation or schema field carries.

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

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

Three sentences, front-loaded with the action and id source, then the reversibility rule, then the exception. Every clause carries information; only the parenthetical '(undo the undo to bring it back)' is mildly redundant with the preceding clause.

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

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

For a two-parameter mutation with an output schema available, the description covers the action, the id provenance, the reversibility model, and the failure/exception cases. There is nothing an agent needs to know to call this correctly that is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds provenance for change_id (originating from postkey_get_edit or postkey_edit_video) and clarifies that changes may belong to either the caller or another person, which the terse schema text ('The change id to undo, from the edit's changes') does not convey.

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 ('Undoes one change to a video edit') with explicit scope ('one change', 'yours or the person's'), and distinguishes itself from postkey_edit_video by naming it as the restore alternative. An agent can tell this apart from postkey_edit_video or postkey_get_edit without opening a schema.

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

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

Gives the precondition for the change_id (from postkey_get_edit or postkey_edit_video), two explicit exclusion cases (already-undone changes are refused; the first auto-edit line cannot be undone as a whole), and routes the excluded case to a named alternative. When-not-to-use guidance is stated rather than implied.

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