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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds genuinely non-obvious side effects beyond them: the opt-in email fires immediately, paused workspaces suppress it, and unsubscribed/bounced addresses are silently refused. It also explains the retry contract for idempotency_key. However it never says what a success response looks like (created vs. updated, whether a confirmation email was queued), which is the main remaining behavioral gap for a mutation tool with no output schema.

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

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

Every sentence carries distinct, decision-relevant information: scope, opt-in mechanics, the paused-workspace edge case, the tag follow-on, prerequisites, and the retry contract. The purpose is front-loaded in the first sentence and there is no filler or repetition.

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

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

For a 5-parameter mutation tool with annotations present and no output schema, this covers the full decision surface: consent eligibility, irreversible side effects, prerequisites, suppression conditions, and retry safety. The only thin spot is the shape of the returned answer, which is hinted at ('the answer says so') but not enumerated.

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

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

Schema coverage is only 40%, so the description must carry the weight, and it does for the two non-obvious parameters: askToConfirm is explained as double opt-in with immediate send timing, and idempotency_key gets an explicit same-key-on-retry rule. firstName and lastName are left entirely to their self-evident names and maxLength constraints, which is an acceptable but real omission.

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 the upsert semantics spelled out: 'Adds a person to the contacts, or updates the contact with that address.' It also scopes the eligible population ('only for someone who asked to hear from the workspace') and points to postfjord_tag_contact for the follow-on step, so it is distinguishable from postfjord_list_contacts and the other contact-adjacent siblings.

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

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

Gives an explicit when ('someone who asked to hear from the workspace'), an explicit when-not ('never an address found elsewhere'), a prerequisite (email switched on plus the Publish scope), and a named follow-on (postfjord_tag_contact). It even adds a pre-call caution: confirm with the person before setting askToConfirm 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?

Annotations already mark it non-read-only but non-destructive; the description adds key side effects: it returns text only, persists nothing, and consumes workspace AI budget. It does not detail budget limits or error behavior, but the main behavioral traits are disclosed.

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

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

Four compact sentences, front-loaded with the core action and scoping, followed by alternatives and caveats. No wasted language.

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

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

For a no-output-schema tool, it explains that the return is text only and nothing is persisted, plus when to use it and that it consumes budget. The remaining gap is the unspecified shape of per-channel output and undocumented optional parameters, but core invocation needs are covered.

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

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

With 0% schema description coverage, the description must explain four parameters, but it only covers 'brief' and 'channels' at a high level. Optional 'tone' and 'mediaSummary' are not mentioned, and the channel object fields are left to the schema names.

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

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

The description gives a specific verb and resource ('draft text per channel from a brief') and immediately distinguishes the sibling paths: create_draft for saving and repurpose_idea for multi-channel plus email. An agent can select it without opening either schema.

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

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

It states when to use the tool (explicit user request for Postfjord's composer), when not to (usually write the post yourself), and names alternatives for saving and multi-channel repurposing. The routing guidance is explicit.

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

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

Goes far beyond the destructiveHint annotation: discloses that reschedule needs a publish-capable key and is refused while the workspace is paused, that delete is permanent and scope-limited by key level, and that publish-in-progress/published posts are never touched and return as skipped with a specific code list. It also prescribes a confirmation step before destructive deletes.

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 selection rule and alternatives before the dense action-by-action detail. It is a long single paragraph, but nearly every clause carries operational information; minor loss for density that could be broken into a short list.

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?

A destructive, multi-action bulk tool with no output schema is fully covered: actions, key requirements, refusal conditions, skip codes, and retry semantics are all present. Nothing an agent needs to call it safely is missing.

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

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

At 80% schema coverage the baseline is 3, but the description adds real meaning: negative shift moves earlier, startAt anchors the earliest post while others keep spacing, and the idempotency_key retry contract (first answer replayed, nothing made twice). These are behavioral semantics 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+resource ('one action on up to 200 posts') and explicitly names the scope boundary against siblings postfjord_update_post and postfjord_schedule_post for single-post edits. The scale limit and per-post result shape are stated outright.

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?

Opens with the exact selection condition ('when the same change applies to many posts') and names the alternatives for the single-post case. Each of the four actions is then given its own applicability rules (reschedule for scheduled/drafts-with-date, draft for scheduled/cancelled, delete for which statuses).

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

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

Goes well beyond the destructiveHint/idempotentHint annotations by spelling out exactly what happens to recipients (already-delivered keep it, nobody else receives it), that drafts get nothing sent, that cancelled emails cannot be rescheduled, and that the Schedule and publish permission level is required. This is the kind of detail an agent needs before firing a destructive call.

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

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

Front-loaded with the core action, then mode semantics, then the permission prerequisite. The phrasing "By default one that has not started going out turns back into a draft" is slightly convoluted, 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 two-parameter destructive mutation with annotations covering the safety profile and no output schema, the description supplies outcome semantics, irreversibility, and auth requirements. Only minor gaps remain, such as error behavior for an invalid campaignId or an already-cancelled email.

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 0%, so the description must carry the load: it explains "unschedule" and "cancel" semantics and implies "auto" via "By default." campaignId is left untouched, but its role is self-evident from the name and the regex-constrained format is 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?

"Stops an email" gives a specific verb and resource, and the body clarifies that the target is a scheduled/sending campaign (draft-revert vs in-flight cancel). It does not explicitly distinguish itself from near-siblings like postfjord_cancel_post or postfjord_schedule_campaign, so the agent must infer by resource type.

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 effectively documents when each mode applies: default/'auto' reverts unstarted emails to draft and cancels in-flight ones, "unschedule" only reverts, "cancel" always cancels. It gives the consequences that drive the choice but never states when not to use this tool in favor of a sibling.

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

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

Goes well beyond the destructive/idempotent annotations by spelling out exactly what is destroyed (unsent posts, DM automation, paused emails, signup form, page) versus preserved (contacts, tags, consents, already-sent posts, pages unless takePageDown). Also discloses the Publish scope requirement and that it works while the workspace is paused.

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, but the body is a dense run-on with repeated framing ('This is a Flow in Postfjord', 'A Flow Bo planned', 'A Flow the person built step by step') and restates schema-documented mode/takePageDown behavior. Acceptable length for a complex destructive tool but poorly structured and partially 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?

For a destructive, no-output-schema, multi-mode tool, it covers everything an agent needs: branch conditions, side effects, what survives, permission scope, and reopening path. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the prose adds real meaning: it explains that close keeps existing members receiving every email including birthday emails and leaves closedAt set, and that takePageDown pulls the page offline only for builder Flows. This enriches the terse enum/boolean descriptions rather than merely repeating 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?

States a specific verb (stops/cancels a goal) and resource (a Flow goal), and explicitly names the counterpart operation postfjord_launch_goal that reopens what this closes. The multi-branch explanation makes the effect unmistakable versus siblings like update_goal.

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 condition-based routing: stop vs close for builder Flows, permanent stop for Bo-planned Flows, draft-revert for step-by-step builds, fairly explicitly telling the agent which variant applies. It also instructs the agent to ask the person and confirm first. Lacks only explicit comparison to non-goal siblings like postfjord_cancel_campaign.

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

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

Annotations already declare the operation is not read-only, is idempotent, and is non-destructive. The description usefully adds the resulting state, namely that the item stays in the queue as cancelled, which is behavioral context beyond the annotations and does not contradict them.

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

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

Two short sentences, front-loaded with the action and followed by the key state outcome. There is no redundant or filler text.

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

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

For a simple one-parameter mutation whose annotations cover idempotency and non-destructiveness, the description conveys the essential outcome. The only notable gap is that it does not describe the required postId parameter.

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

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

Schema description coverage is 0%, and the only parameter, postId, has no description in the schema. The description refers to 'a scheduled post' but never names or explains postId, so it does not compensate for the missing 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?

The description states a specific verb and resource: cancel a scheduled post. The clause 'so it will not be published' plus 'stays in the queue as cancelled' distinguishes it from a permanent delete sibling such as postfjord_delete_post.

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

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

The description implies when to use it: when a scheduled post should not publish but should remain visible as cancelled. It does not explicitly mention alternatives such as delete_post or update_post, so the guidance is implied rather than directive.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description adds the crucial behavioral facts those annotations don't carry — the automation is created paused and answers nobody until enabled, the Draft scope is required, and retries with the same key are safe. It doesn't state what happens on ValidationFailure of sameKeywords beyond "say so", but the coverage is rich. No contradiction: idempotentHint=false describes default behavior, while the description explains idempotency is opt-in via the key.

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

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

Front-loaded with purpose and the sibling distinction, then triggers, then steps, then operational rules. It is dense and long — a single run-on block covering triggers, steps, brand-voice advice, scope, approval flow and idempotency — but nearly every sentence carries non-redundant 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 complex tool with nested oneOf steps, 6 parameters, no output schema and no destructiveness annotations, the description covers what the agent needs: trigger semantics, step types and ordering, scope requirement, the paused-by-default behavior, the approval workflow and idempotency handling.

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

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

With 67% schema coverage, the description meaningfully compensates by explaining each trigger type's constraints (comment_keyword needs a DM with a link; postIds "any" or "next"; ref_link uses exactly one channel; after_purchase events ["booking","sale"]) and the step vocabulary, including ordering rules like aiReply last and the fact that remove-tag/set-field/branch steps must be added in the app. It doesn't restate every nested field (e.g. likeComment, channelIds), relying on those 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 ("Creates a DM automation on Instagram or Facebook") plus a crucial scope qualifier ("always paused: it answers nobody until it is switched on"). It explicitly names the sibling it is not — "an email series that starts by itself is postfjord_create_email_automation" — so an agent can route correctly without opening either schema.

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

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

Explicitly says when to use it versus postfjord_create_email_automation, names the follow-up step (switch it on with postfjord_set_automation only after the person approves), and gives retry guidance with the same idempotency_key. Nothing about selection or sequence 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 destructiveHint=false and openWorldHint=false, and the description adds material context beyond them: the 90-day maximum range, workspace-wide visibility, and the retry contract via idempotency_key. The distinction between a fresh key per action and reusing a key on retry is genuinely useful operational detail. Minor tension with idempotentHint=false is resolved by the text itself, since idempotency only holds when the key is reused, so this is not a contradiction.

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

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

Front-loaded with the concrete action and examples, then constraints, then retry behavior — a sensible order. It is slightly wordy in the idempotency sentence and repeats the single-day rule that the `to` schema field already states, 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?

Six parameters, no output schema, and the description covers duration limits, visibility, parameter defaults, and retry semantics — everything an agent needs to call it correctly and safely retry. The only gap, what identifier comes back, is minor for a note-creation tool with a companion list_calendar_notes.

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 a cross-parameter constraint not encoded in the schema ("a note covers at most 90 days") and restates the single-day default for `to` in prose. The idempotency_key retry semantics also get more explanation than the schema's own field description provides.

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

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

The description names the specific action (put a note on a calendar) and its scope (one day or a range, visible to everyone in the workspace), with concrete examples like "Black Friday" and "Studio closed". It explicitly separates itself from content-publishing siblings by stating "nothing is posted or sent," so an agent can distinguish it from schedule_post or create_draft 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 explains the shape of use ("Leave out to for one day") and rules out the obvious wrong expectation by clarifying the note is not published. It does not explicitly point to update_calendar_note, delete_calendar_note, or list_calendar_notes for the nearby operations, so sibling routing is left to the tool name alone.

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: without scheduledAt it saves a draft and returns validation problems; with scheduledAt it must pass validation and the engine publishes at that time. It also discloses the idempotency contract for retries after timeouts, including the default 10-minute same-call window, which is real behavioural information the annotations (idempotentHint=false) do not convey.

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

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

The critical discriminator (what it makes, and which sibling to use instead) is front-loaded, and most sentences carry an operational rule. It is long, though, and a few clauses (the crop/"whole" explanation) restate what the target schema already documents, which slightly dilutes the signal.

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

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

For a 12-parameter, nested-object mutation tool with no output schema, the description covers the main modes, prerequisites, idempotency, and what dry_run returns. It is thinner on what a successful non-dry-run creation returns and on permission requirements, which matters for a tool that can schedule real publishing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics: the presence/absence of scheduledAt switches draft vs scheduled mode, mediaIds come from postfjord_list_media, and targets.fit mode "whole" is the remedy when a crop would cut people or words. Some of this (the fit modes) duplicates the schema text.

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

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

"Makes one new post" gives a specific verb and resource, and the second sentence names three sibling tools (schedule_post, update_post, bulk_update_posts) with the exact case each covers. An agent can distinguish this tool from its neighbours 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 routing: existing drafts go to schedule_post, single edits to update_post, batch moves/removals to bulk_update_posts. It also states prerequisites (check brand profile and channel limits, Instagram needs an image or video, dry_run first, preview before scheduling) rather than leaving ordering to inference.

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

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

Annotations only declare the safety profile (readOnly=false, destructive=false); the description adds what actually happens: nothing is sent on creation, the automation stays a draft until explicitly started, and a scope/permission is required. It also explains the idempotency contract in plain terms ('send the same idempotency_key: the first answer comes back and nothing is made or sent twice'), which complements rather than contradicts idempotentHint=false (bare calls are not idempotent; a key makes the retry safe).

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 disambiguating sibling comparisons, then purpose, triggers, approval flow, and retry rules in a sensible order. It is dense and somewhat run-on (long parenthetical trigger clause), but nearly every clause carries actionable information.

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

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

For a complex nested tool with no output schema, it covers scope, trigger sourcing, timing defaults, and the human-approval gate. The one gap is what the call returns (e.g., the automation id needed for postfjord_set_email_automation), which the agent must infer.

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?

Adds real semantics beyond the schema: trigger-type meanings and where ids come from (formId from postfjord_list_signup_forms or "any", segmentId from postfjord_mail_overview), that a new tag name creates the tag, and the delayDays default of 2 with first-email-goes-immediately behavior. It does not touch the large block/email body parameters, but those are already documented exhaustively in the schema.

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

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

States a specific verb and resource ('Creates an email automation as a draft') and immediately bounds it ('a series of 1 to 10 emails'). It explicitly distinguishes two siblings: 'one email to a list is postfjord_draft_campaign' and 'DM replies on Instagram and Facebook are postfjord_create_automation', so an agent can route 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 when-to-use via the sibling routing sentence, and describes the required review-then-launch flow: show the user each email and its trigger, then start with postfjord_set_email_automation only after approval. It also states prerequisites ('Needs email switched on and the Draft scope') and names the alternative for the Instagram/Facebook case.

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

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

Beyond the annotations it discloses that nothing goes live on create, that drafts count against the plan allowance, that the brand kit sets colours, and that a retry with the same idempotency_key replays the first answer rather than creating twice. The idempotentHint=false annotation is not contradicted because the description frames idempotency as conditional on the supplied key. It does not describe failure modes beyond publish-blocking checks.

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 first two sentences are well front-loaded and the scope/publish gate comes before detail. But roughly two thirds of the text is a block-by-block tutorial that duplicates the blocks parameter description word for word, which is bulk the agent already has in the schema; those sentences do not earn their place in the tool description.

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

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

For a 12-parameter mutation tool with no output schema, the description covers the return shape ("the page and the checks that still stop a publish"), the publish gate, idempotency/retry semantics, content-truthfulness constraints and the link/bracket syntax. An agent could call this correctly from the description plus schema without further discovery.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, and the long block-composition passage in the description (hero/layout avatar, links, social, countdown, location, booking, bracket rules) is reproduced nearly verbatim from the blocks parameter's own schema description, adding no meaning on top of it. The genuinely additive content — recommended page recipes for bio vs landing — is minimal. Baseline 3 is right.

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 two sentences state a specific verb and resource ("Creates a draft page") and immediately name the boundary with the sibling that publishes (postfjord_publish_page), so an agent can tell creation from publishing without opening a schema. The kind=bio vs kind=landing distinction is then spelled out with scope differences (one per workspace vs many per plan).

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

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

It gives clear when-to-use context and routes to prerequisites: image ids come from postfjord_list_media, form ids from signup forms in postfjord_list_pages, retained block ids from postfjord_get_page, and publishing needs postfjord_publish_page plus the owner's yes. What is missing is an explicit exclusion — nothing says to use postfjord_update_page instead when the page already exists, despite that sibling being present.

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

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

Goes well beyond the annotations: discloses that the form is public and live immediately, that signups trigger a double opt-in confirmation email (an outbound side effect), and that tags are only applied after confirmation. It also carries quota and auth-scope requirements and explains retry semantics, none of which the readOnly/destructive/openWorld hints 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 dense sentences with no filler, and the highest-value facts (what it makes, that it is live, the sibling boundary) are front-loaded. Every sentence carries a distinct operational fact.

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

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

For a 14-parameter creation tool with no output schema, the description covers the return value ('the answer has its public link'), the side effects, the prerequisites, and the quota. 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?

Schema description coverage is 100%, so all 14 parameters (including why, tags, askBirthday and idempotency_key) are already documented in the schema with examples. The description adds only the retry-situation framing for idempotency_key, which is close to what the schema already says ('send the same one again only when you retry').

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

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

States a specific verb+resource ('Creates a signup form for the email list') and immediately pins down the important scope detail that it goes live at once rather than saving a draft. The sibling redirect to postfjord_plan_goal makes the boundary unmistakable.

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

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

Explicitly names the alternative (postfjord_plan_goal) and the situation that selects it, plus concrete preconditions: email must be switched on (postfjord_mail_overview), the Publish scope is required, and a workspace caps at 20 forms. It also adds a workflow instruction ('Confirm the texts with the person first') and retry guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety bar is lower. The description still adds real value: it says the deletion is workspace-wide and irreversible, and clarifies the side effect that scheduled posts on those days remain untouched — context 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?

Three short sentences, with the action and scope front-loaded and the irreversible/non-cascading consequences following immediately. No filler.

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

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

For a single-parameter destructive delete with full schema coverage and annotations, the description supplies the missing behavioral nuance (irreversibility, workspace-wide effect, posts unaffected). No output schema exists, but a delete's return value is unlikely to be needed; only alternative-route guidance is absent.

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

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

Schema coverage is 100% and the sole parameter's description already explains where the noteId comes from. The description adds nothing about noteId format or lookup, so baseline 3 applies when the schema carries the burden.

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 ('Deletes a calendar note') plus the scope ('for everyone in the workspace'), which distinguishes it from a private/local delete. It does not explicitly name the sibling (e.g., update_calendar_note) that an agent should prefer for modification, though the scope detail does most of the differentiating work.

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

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

The 'ask the person you work for first' line gives a confirmation cue, which implies this is a deliberate, rarely-used action. However, it never names an alternative or states when not to use it (e.g., 'to edit rather than remove, use update_calendar_note'), leaving routing to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description's one contribution is the state restriction (only draft/cancelled posts), which is genuinely new context, but it doesn't say whether deletion is permanent or whether an invalid-state call errors.

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

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

A single short sentence, front-loaded with the verb, with no filler. It's efficiently written, though the brevity edges into under-specification rather than pure economy.

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

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

For a destructive, idempotent single-parameter tool with annotations carrying the safety signals, this is close to adequate: the state restriction is stated and there's no output schema to explain. Still missing is whether the delete is reversible (trash vs permanent) and what error occurs on a published post.

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 postId parameter has 0% schema description coverage — only a regex pattern — and the description never mentions it. With low coverage the description is expected to compensate with format or provenance guidance, and it provides none.

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 ('Deletes a ... post') and narrows scope to drafts and cancelled posts, which distinguishes it from sibling postfjord_cancel_post and postfjord_update_post. It stops short of telling the agent what happens to a published post, but the core action is unambiguous.

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

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

The phrase 'draft or cancelled' implies a precondition for use, but the description never says what to do instead when the post is in another state, nor does it point at postfjord_cancel_post as the prior step. Usage is inferable rather than stated.

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

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

Annotations only declare the generic flag set (readOnly=false, destructive=false, idempotent=false); the description goes far beyond by stating 'Nothing is sent', that AI drafting consumes the workspace AI budget, that the response reports the reached confirmed-contact count, and how idempotency_key makes retries safe (first answer returned, nothing duplicated) despite idempotentHint=false. It also discloses the handoff path editUrl for humans.

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 each sentence carries information (routing, targeting defaults, authoring paths, images, sending handoff, retry semantics). The opening clause about automation series slightly delays the core statement, which is the only structural weakness.

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 13-parameter mutation with no required fields and no output schema, the description covers what is created, what is targeted by default, both authoring modes, where image ids come from, how the result is returned, and how to send it afterwards. The heavy block schema is self-documented at 92%, so no further param detail is needed.

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

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

Schema coverage is 92%, so the baseline is 3. The description still adds meaning the schema does not: tags are matched case-insensitively, and the absence of both tags and segment means everyone who opted in ('everyone who said yes'). It doesn't explain name/language/logo beyond the schema, keeping it short of a 5.

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

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

States a concrete verb and resource: 'Creates a new email as a draft' in the workspace's brand styling, and explicitly distinguishes it from postfjord_create_email_automation (self-starting series) and postfjord_schedule_campaign (sending). An agent can route correctly 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?

Names alternatives and the conditions that pick them: use postfjord_get_brand_profile first for writing rules, postfjord_list_media for image ids, postfjord_schedule_campaign to actually send (with its required level). It also says when to choose the self-written path vs the AI brief path. Nothing 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?

Adds real context beyond the annotations: it consumes the workspace AI budget (a cost), returns text only and sends nothing (clarifying that destructiveHint=false means no side effects on the conversation), and requires a key with the Drafts or Publish scope. It stops short of describing length, language, or failure modes, which keeps it at a 4.

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

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

Purpose is front-loaded and each sentence carries usable information (cost, return shape, approval flow, scope). It is slightly dense at six sentences and the approval guidance could be tightened, but nothing is filler.

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

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

For a two-parameter generation tool with no output schema, the description covers what is returned (text only plus the needsPerson flag), what is not done (nothing sent), auth scope, and the follow-up tool. An agent can call and act on it correctly without opening anything else.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema; the description only implies that conversationId refers to a single conversation and that instruction shapes tone. 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: ask Postfjord's AI to write a reply to one conversation in the brand voice. The parenthetical title 'sends nothing' plus 'Returns the text only' separates it cleanly from postfjord_send_reply and from the other drafting siblings.

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

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

Gives an explicit workflow: show the draft to the person you work for, then send with postfjord_send_reply only after approval. Names the alternative tool and the condition that selects it, and explains the needsPerson branch for escalation.

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 readOnlyHint/openWorldHint=false, the description discloses material behavior: results are 'cut to what the plan keeps', reach exists only 'where the platform shares it', best-time is normalized 'against each channel's usual', and missing data is explained in notes. These coverage/completeness caveats are exactly the context annotations cannot carry; only rate limits or cost hints are absent.

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 in the opening clause and the long metric enumeration is dense but each item earns its place by describing a distinct return element. It is on the heavy side for a single-parameter read tool, but 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?

With no output schema, the description carries the return-value burden and does so by enumerating the metric groups plus the 'notes' field that explains gaps. Time zone, normalization basis, and the days window are all covered; only fine-grained response shape (e.g. per-channel nesting) is left unstated.

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

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

Schema coverage is 0% and the schema only encodes allowed constants, so the description must compensate — and it does, stating the four accepted values, the default of 30, and the plan-based truncation of the window. It adds real meaning over the bare anyOf/const list, though nothing about how the window is anchored (e.g. calendar days vs rolling).

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

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

The description names a specific verb (get the numbers the Analytics screen shows) and then enumerates the exact metrics returned: channel followers and change, posts/likes/comments as counts and rates, reach where available, top posts with text and link, and best weekday/hour. That level of content specificity effectively separates it from siblings like postfjord_plan_metrics or postfjord_get_weekly_signals even though those are not named.

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

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

'Use it to answer what performed and to plan posts like the ones that did' gives a clear, concrete usage context rather than leaving intent implicit. It does not exclude alternatives or state when another analytics-ish sibling should be preferred, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds one genuinely behavioral detail beyond that: the strategy section is null when none exists, which prevents misreading an empty field. It says nothing about auth requirements, error cases, or whether the profile can be entirely absent, so it is useful but thin.

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?

Every clause is informative, but the first sentence is a dense 45-word run-on with a nested parenthetical and the awkward phrase 'the content strategy as strategy (goal, positioning, ...)' that is hard to parse on one read. The short second sentence is well-placed and front-loads the action.

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

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

With no output schema, the description must carry the return shape, and it does so by enumerating the profile sections and the strategy sub-fields (goal, positioning, pillar share, posts per week, lean into, avoid). Nesting depth and exact value types remain implicit, but an agent has enough to call it and interpret the result.

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 (100% coverage, empty schema), so the baseline is 4. There is nothing parameter-level the description needs to explain, and it does not waste words inventing any.

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

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

The description enumerates the exact resource contents (voice, audience, do/don't rules, pillars, hashtags, example posts, strategy) and scopes it to 'this workspace,' which makes it unmistakable that this is the brand-profile read. It never uses a retrieval verb, so the name/title carries that part, and it doesn't explicitly contrast with any sibling.

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

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

'Read it before writing any post' gives a clear, actionable trigger that an agent can apply directly before calling create_draft, ai_compose or schedule_post. It states when to use it but offers no when-not conditions and no named alternatives, which keeps it short of a 5.

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

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

'Read only' merely restates readOnlyHint=true, earning no credit. The description does add real value about the payload shape: unsupported blocks come back as type 'keep' with an id, product blocks are point-in-time snapshots, boxed blocks carry a box id, and A/B-tested subjects include abTest data. With no output schema, that return-shape disclosure is the main contribution; error/not-found behavior and the fact that content may not round-trip into the draft form are left implicit.

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

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

Front-loaded with the read-only guarantee and the one-email scope, then moves into return details that each earn their place. Some sentences are dense run-ons (the 'keep' block parenthetical), but little is wasted.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly for the unusual cases (unsupported blocks, snapshotted products, boxes, A/B tests). The main omission is the sole input parameter, plus any note about authentication or failure behavior.

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

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

Schema description coverage is 0% and there is one required parameter, yet the description never mentions campaignId, its format, or where to obtain it (presumably from postfjord_list_campaigns). The description therefore fails to compensate for the coverage gap.

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

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

States a specific verb and resource: 'One email with its status and its content', enumerating subject, preheader and blocks. It implicitly separates itself from postfjord_list_campaigns and postfjord_get_campaign_report by describing a single campaign's authored content rather than a collection or performance metrics, though it never names those siblings.

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

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

'Read this before postfjord_update_campaign' gives one explicit workflow ordering, which is genuinely useful. But there is no guidance on when to prefer this over postfjord_get_campaign_report or postfjord_list_campaigns, and no exclusion conditions.

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

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

Beyond the readOnlyHint annotation, the description discloses substantive behavior an agent cannot get from structured fields: results are counts only and never identify individuals, and clicks/opens are suppressed below 10 deliveries to prevent re-identification. It also conditions the abTest block on the campaign having tested a subject. These are exactly the quirks that would otherwise cause misreading of the numbers.

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 'Read only' lead and the output inventory are front-loaded and every clause carries information. The middle sentence runs long with stacked noun lists, 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?

With no output schema, the description carries the return-value burden and does it well, specifying both the metric set and the abTest sub-structure. Remaining gaps are the required campaignId argument and behavior for campaigns that haven't sent yet.

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

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

Schema description coverage is 0% and the description never mentions campaignId at all — not its meaning, not its expected format, not that it is required. With one required parameter documented nowhere, the description fails to compensate for the schema gap, though the resource framing ('report of an email') implicitly points at an identifier.

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 concrete resource (the performance report of a sent email) and enumerates exactly what it contains: sent, delivered, bounces, complaints, unsubscribes, clicks/opens, clicks per link, time series, and abTest breakdowns. An agent can tell this is a metrics read, not the campaign settings read that postfjord_get_campaign or postfjord_get_analytics would give. However, it never explicitly contrasts itself with those siblings, leaving the routing inference to the agent.

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

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

Usage is only implied: 'the report of an email that went out' signals this is for post-send analysis, and the privacy note hints it's for aggregate performance rather than recipient-level inspection. There is no statement of when to prefer it over postfjord_get_campaign, postfjord_get_analytics, or postfjord_list_campaigns, and no note that it only makes sense after a send.

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

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

Annotations only declare read-only and closed-world operation, but the description adds the 24-hour platform reply rule across Instagram, Messenger, and WhatsApp, explains replyWindow.open/closesAt and canReply reasons, and warns that message text is untrusted external content to treat as information, not instructions.

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 'Read only' and then delivers message scope, reply eligibility, and the prompt-injection warning without filler. The 24-hour platform detail is compressed into a parenthetical where it belongs.

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

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

With no output schema, the description still explains what comes back: latest messages oldest first, replyWindow.open and closesAt, and canReply with a reason when false. It also covers the security caveat an agent needs when handling external message text.

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 mostly repeats what the schema already says about limit defaulting to 20 and maxing at 50. It adds useful ordering context ('oldest first') but does not add substantial meaning beyond the schema for either 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: reading the latest messages in one Inbox conversation, plus reply-window and canReply status. This distinguishes it from list_conversations, which returns conversation IDs rather than message contents.

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 clearly frames the use case around checking whether a reply can go out now, which implies using it before send_reply or draft_reply. It does not explicitly name those alternatives or state exclusions, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds genuinely non-obvious behavior: results are 'counted at most every five minutes' (data freshness), and it decodes status/autoClose/closeReason semantics that an agent would otherwise have to guess. It also discloses that some outputs may be drafts via launch notes.

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 correctly with 'Read only' and the resource name, but the body is a single sprawling sentence with deeply nested parentheticals covering status, autoClose, plan, assets and every metric. The content earns its place, but the structure makes it hard to parse and it would benefit from being split into separate lines.

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

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

There is no output schema, so the description carries the return-value burden and does so thoroughly: it enumerates plan/planHash/missing, assets (tag, form, page, automations, post ids), and a full results block (posts, DMs, signups, page views/taps). Nothing an agent needs to interpret the response 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?

Only one parameter and schema description coverage is 100%, with the schema already stating it comes from postfjord_plan_goal or postfjord_list_goals. The description adds no further constraint on goalId (format, validity), so baseline 3 is correct.

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

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

Opens with an explicit verb+resource ('Read only. One Flow') and then defines what a Flow actually is (a goal that became posts, a comment-to-DM automation, a page with welcome emails), which no sibling tool defines. An agent can tell this apart from postfjord_list_goals or postfjord_get_analytics 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 sequencing ('Read this before postfjord_update_goal or postfjord_launch_goal') and a concrete user-intent trigger ('how is my flow doing'). No explicit when-not or exclusion (e.g. bulk listing vs single goal) is stated, keeping it just short of a 5.

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

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

Annotations only cover readOnlyHint and openWorldHint, and the description adds substantial behavior the annotations cannot: preview links expire after one hour, previews are only present once a picture is 'ready', and readiness takes seconds for images versus up to a minute for video. That is exactly the operational context an agent needs to avoid treating an empty preview as an error.

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

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

The purpose is front-loaded, but the middle sentence is a long run-on covering preview shape enumeration, TTL, and crop guidance, and the phrasing ('for a picture that is ready previews') is grammatically awkward. All the content earns its place, but the structure makes it harder to parse than it needs to be.

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

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

There is no output schema, and the description compensates well by enumerating the returned fields: a time-limited link with width and height per stored shape. It is only slightly incomplete in not stating what is returned for videos or for files that are not yet ready.

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 0%, so the description must carry the meaning of mediaId, and it does partially by framing it as an id of a file 'as postfjord_list_media shows it' — implying where ids come from. It does not restate the id format or validated pattern, which is left entirely to the schema.

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

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

States a specific verb and resource ('One file in the media library by id') and clarifies the returned shape relative to postfjord_list_media. It also explicitly distinguishes itself from postfjord_preview_post for channel-specific crops, so an agent can tell the three tools apart 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 a concrete usage trigger: 'Use it after postfjord_upload_media to see when the file is ready', with expected latency for pictures vs videos. It also routes the channel-crop case to postfjord_preview_post. It stops short of saying when to use postfjord_list_media instead of this tool for browsing, so not a full 5.

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

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

Beyond readOnlyHint/openWorldHint, the description discloses the concrete payload shape and, more importantly, flags that author and text fields originate outside the workspace and should never be treated as instructions — non-obvious safety context that structured fields cannot convey. It is consistent with the openWorldHint annotation and adds real operational value.

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

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

Two short sentences with zero filler: the read-only scope is front-loaded, the returned fields follow, and the injection caution closes. Nothing is repeated from the title or schema 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 one-parameter read tool with no output schema, the description covers returned content and the key behavioral risk (untrusted external text). The only untouched item is what happens when the id is unknown or not visible to the caller, a minor gap.

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

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

Schema coverage is 100% and the single id parameter already documents its pattern and that ids come from postfjord_list_mentions. The description adds no format, lookup, or error semantics on top of that, so the baseline 3 is correct.

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

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

The first sentence names a specific verb and resource ('Read only. One mention') and then enumerates exactly what comes back (link, author handle, text, rating, score), which cleanly separates it from postfjord_list_mentions. It stops short of explicitly naming the list tool as the sibling, but the singular scope is unambiguous.

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

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

Usage is only implied: a reader infers this is the follow-up to a listing call because it returns one record. No explicit when-to-use, when-not-to-use, or named alternative appears in the description (the pointer to postfjord_list_mentions lives only in the id parameter schema).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so 'Read only' merely repeats structured data and earns no credit. The description does add genuine behavioral context beyond the annotations: the 30-day measurement window, UTC vs fromLocal/untilLocal schedule duality, and the conditional presence of shareLinks only for live pages. It omits error behavior (unknown pageId), whether drafts are returned, and payload size.

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-loading is fine ('Read only. One page with...') but the payload enumeration then runs as a single sprawling sentence dense with parenthetical field names, which is hard to scan. Nearly every clause carries information, but the structure would benefit from being broken into distinct chunks (content, scheduling, analytics, share links).

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

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

No output schema exists, and the description does its job by spelling out the returned fields in unusual depth, including naming the shareLinks channels. Gaps remain around the pageId input and edge cases like a missing page or an unpublished page, but for a single-parameter read tool it is close to complete.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it never mentions pageId: no format, no source (e.g., from list_pages), no constraints despite the ^[A-Za-z0-9]{1,40}$ pattern. With one required, totally undocumented parameter, the description does not compensate for the coverage gap.

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

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

States a specific verb and resource (read one landing page) and enumerates the exact payload: blocks, schedules with UTC and local times, SEO title/description, publish check, per-link views/taps, sharedVisits30Days and shareLinks. An agent can distinguish this detail read from postfjord_list_pages or postfjord_get_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 explicit sequencing guidance: 'Read it before postfjord_update_page.' It also explains the practical use of the share links ('paste into a chat or DM so the visit is not counted as Direct'). It stops short of naming list_pages as the way to discover a pageId or stating when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description's added value is the return-shape disclosure (status, permalinks, errors, aspect/fit), which matters because there is no output schema. It says nothing about auth requirements, error behaviour when a postId is unknown, or freshness of status data.

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

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

Two sentences, both load-bearing: the first front-loads what comes back, the second routes away to the sibling. No filler and no repetition of the title.

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

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

With no output schema, describing return contents is the description's core job and it does that well for a single-entity read. What is missing is modest — error/not-found behaviour and any note on how current per-channel status is — but nothing blocks a correct invocation.

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

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

Schema description coverage is 0% for the single required postId, so the burden falls on the description — and it mentions nothing about the identifier. The schema does supply the string type and an ID pattern, which partially compensates. Adequate, but the description contributes no parameter meaning of its own.

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

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

The description names the resource (a single post) and enumerates what it carries back: per-channel status, permalinks, errors, and each channel's aspect/fit. It also distinguishes itself from postfjord_preview_post, so the agent can separate the two without opening a schema. The only weakness is an implicit verb — 'One post with...' rather than an explicit 'Get a single post including...'.

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

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

It gives an explicit routing rule: use postfjord_preview_post to see the pictures themselves, which precisely carves out the one adjacent tool an agent would confuse this with. It does not cover other plausible neighbours such as postfjord_get_analytics or list-type tools, but for a single-resource fetch the context is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description contributes real value by disclosing the record granularity ('attempt-by-attempt') and the exact columns returned, which tells the agent to expect multiple rows per post. It stops short of ordering, pagination, retention window, or what an empty log means.

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

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

A single front-loaded fragment with the resource first and the returned fields second — zero padding. It is telegraphic rather than sentence-complete, but every word carries information and nothing is wasted.

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

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

With one required parameter, no output schema, and read-only annotations, the description covers the essentials of what the tool returns. Gaps remain around result ordering, volume per post, and how to interpret a post with no attempts — details an agent needs to use the output sensibly, though the simple shape limits how costly those gaps are.

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

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

Schema description coverage is 0% and the single postId parameter carries no description or format hint. The phrase 'for a post' weakly ties the parameter to a post identifier, but does not clarify whether it accepts the internal ID, a slug, or a channel-scoped ID. One parameter at zero coverage keeps this at a minimum-viable 3.

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

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

The description names a specific resource ('attempt-by-attempt log for a post') and enumerates the fields it exposes (channel, attempt, status, error), so an agent knows this is a per-attempt publishing audit trail rather than a general post lookup. However, it never explicitly contrasts with close siblings like postfjord_get_post or postfjord_get_analytics, leaving the agent to infer the boundary.

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

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

There is no guidance on when to reach for this tool versus postfjord_get_post (post state) or postfjord_get_analytics (performance metrics). No prerequisites, no mention of what a caller should do with failed attempts. Usage must be guessed entirely from the name and returned fields.

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 readOnlyHint annotation: it defines null as 'not counted, never zero', discloses the 8-week threshold before pattern claims appear, flags that the 'story' field covers only last week, and warns against ROI/causal interpretation. These are exactly the caveats an agent needs to avoid misreporting the numbers.

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

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

Purpose is front-loaded in the first clause, and the long metric enumeration is justified because there is no output schema to document return fields. The trade-off is a dense run-on sentence whose mid-section metric list is harder to parse than it needs to be.

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

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

With no output schema and no parameters, the description carries the full burden of explaining return contents and does so thoroughly — per-week metrics, moving averages, notes, story, patterns, and null semantics are all covered. Nothing essential to calling or interpreting the tool 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?

Zero parameters and a 100% covered schema, so the baseline of 4 applies; there is nothing parameter-level for the description to clarify. The time window is fixed by the tool rather than configurable, and the description states that clearly.

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 framing ('What the posts did week by week') and pins the scope to the last 12 weeks plus the current Monday-to-Sunday UTC window. It is clearly a weekly post-performance report, but it never names or contrasts itself with the obvious sibling, postfjord_get_analytics.

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

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

Usage is implied rather than stated: the weekly granularity and post-centric metrics suggest when to reach for it, but there is no explicit 'use this instead of get_analytics when...' or exclusion guidance. With ~60 siblings including get_analytics and get_campaign_report, an explicit routing sentence would materially help.

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, idempotentHint=true, and openWorldHint=true, and the description adds concrete side effects: the page goes live, posts may publish, DMs start answering, emails send, and missing pictures keep posts as drafts. It also discloses the planHash refusal behavior, the Publish scope requirement, and the idempotency retry contract, all beyond what annotations provide. No contradiction with annotations.

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

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

The description is long and dense, but nearly every clause carries operational weight for a complex six-parameter mutation. It is front-loaded with the purpose and approval precondition, then organized into choices, planHash, partial-launch handling, closed-Flow reopening, and idempotency. Some sentences are run-on and could be tightened, but it is not redundant filler.

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

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

No output schema exists, so the description must explain return-relevant behavior, and it does: notes say what waits and why after launch, retries return the first answer, and nothing is made twice. Combined with coverage of destructive effects, scope requirements, and all parameter choices, the definition is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the schema itself defines all six parameters. The description nevertheless adds meaning: planHash must match the approved plan or launch is refused, postsAs controls whether posts publish or wait, and startEmails/turnOnAutomation must be explicitly approved by the person. It reinforces rather than repeats the schema, though for two params it adds little beyond the schema text.

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

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

States a specific action (launch a Flow) and enumerates exactly what gets created in one go: tag, signup form, landing page, welcome email automation, comment-to-DM automation, and posts. This clearly distinguishes it from planning siblings like postfjord_plan_goal and postfjord_get_goal, which do not launch anything.

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

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

Provides explicit when-to-use conditions: only after showing the plan from postfjord_get_goal and receiving approval on the plan and three choices. It also gives when-to-retry guidance, explains reopening a closed Flow, and warns never to enable a choice the person did not ask for. Alternative paths are implied through get_goal/update_goal references.

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 openWorldHint=false, and the description reinforces 'Read only' while adding useful domain context: the exact status values including on_but_over_plan_limit and the meaning of that state. Doesn't cover pagination or auth, but the annotated safety profile covers most of that burden.

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 resource and packs field/status explanations into a single dense but purposeful passage. Slightly long and run-on, but nearly every clause conveys return-field meaning.

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

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

With no parameters and no output schema, the description compensates by naming the returned fields (id, name, status, trigger, steps, counts) and explaining status semantics. Complete enough to call 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?

Zero parameters, so the baseline of 4 applies. The description focuses entirely on return shape rather than inputs, which 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 ('The workspace's DM automations') and resource, enumerating subtypes (comment to DM, keywords, story replies) that separate it from the sibling list_email_automations and from mutating siblings like create_automation/set_automation. An agent can identify this as the read-side listing 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 says to 'Read it before switching one on or off,' pointing at the set/switch controls. Clear context for when to call, though it doesn't name the exact sibling (set_automation) or note exclusions.

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

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

Annotations already establish this is a safe, closed read, and the description adds a real behavioral trait beyond them: the response gains a notes field only when both from and to are supplied. It does not explain the effect of limit or default ordering, so it stops short of full disclosure.

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

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

A single front-loaded sentence names the two filtering modes before the parenthetical asides, so nothing important is buried. The nested parentheses make it dense but every clause carries information.

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

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

For a read-only list tool with no output schema, the description covers date semantics, status values, and the conditional notes field, which is enough to call it correctly. Missing are limit/pagination behavior and default result ordering, the main remaining gaps.

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

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

Schema coverage is 50%; from/to are well documented in the schema. The description compensates for the undocumented status parameter by enumerating all seven values, which the schema does not, but it says nothing about the limit parameter, leaving one of four parameters unaddressed.

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 the specific resource (scheduled posts) and the two filtering modes (date range or status), so the agent knows exactly what it returns. It references the sibling postfjord_list_calendar_notes only to explain where notes come from, not to draw a usage boundary, so differentiation is only partial.

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 condition 'with both from and to' is given for the enriched notes result, which implies usage, but there is no explicit when-not or 'use X instead' routing against list_calendar_notes or other list tools. The agent must infer that this tool covers posts and the other covers notes only.

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 openWorldHint=false, and the description reinforces safety with 'Read only.' It adds genuinely new behavior: the inclusive date bounds, the workspace time-zone interpretation, and the 400-day cap on the requested range. It does not say how many notes can come back or how truncation is signaled.

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 safety qualifier and the core 'what' are front-loaded, and every sentence carries content. The opening clause ('The notes on the calendar with a day between from and to') is slightly convoluted and could be stated more directly, keeping it from a 5.

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

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

With no output schema, the description carries the burden of describing return values and does so fully (title, optional text, colour, covered day range). Combined with the range cap, time-zone semantics, and the planning rationale, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point because it clarifies that both bounds are inclusive and interpreted in the workspace time zone — semantics the schema's 'First day' / 'Last day' wording 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?

The description uses a specific verb ('The notes on the calendar...') and enumerates the returned fields (title, optional text, colour, covered days), so the resource is unambiguous. It does not, however, distinguish itself from the sibling tool `postfjord_list_calendar`, which an agent could easily confuse with this one.

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

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

It gives concrete usage context: 'Notes mark things like a sale, a holiday or a course start; read them before you plan posts for those days,' which tells the agent when the tool is valuable. It offers no explicit exclusion or alternative (e.g., when to use `postfjord_list_calendar` instead), so it falls short of a 5.

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

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

Goes beyond the readOnlyHint annotation by disclosing sort order (most recently changed first), the pagination contract, and a non-obvious data quirk (clicks hidden below 10 deliveries). It does not mention the default page size or maximum, which affect how many calls are needed.

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

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

Two tight sentences, front-loaded with the safety signal, then the returned field inventory, then the pagination instructions. Every clause carries information; nothing 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?

With no output schema, the description usefully enumerates returned fields (id, name, kind, status, subject, schedules, recipients, report numbers, editUrl), which is exactly what the agent needs to consume results. Missing only the default limit and explicit sibling routing, which keeps it short of full completeness.

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

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

Schema coverage is 50% and the description compensates: it spells out the enumerations for kind (campaign/automation) and status (draft through failed), and explains that cursor comes from nextCursor. limit is left to the schema and its 1-50 bounds are not restated.

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 ('Email campaigns and automation emails' listed most recently changed first) so the agent knows this is a paginated list endpoint. It does not distinguish itself from close siblings such as postfjord_list_automations / postfjord_list_email_automations, which overlap with the 'automation emails' scope it claims.

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

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

Usage is implied rather than stated: 'Read only' signals a safe lookup and 'Pass nextCursor back as cursor for more' explains the pagination loop. There is no guidance on when to call this versus postfjord_get_campaign or the automation-specific list tools for a narrower view.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by itemizing the returned fields, including non-obvious ones like per-format picture shapes and per-platform limits, which matter when composing posts. It does not mention auth scope or ordering, keeping it short of a 5.

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

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

Two sentences, front-loaded with the resource and its fields, ending with the actionable channelIds hint. The parenthetical listing of limits is dense but readable; a bulleted breakdown would scan faster but this earns 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?

With no output schema, the description carries the full burden of explaining return values, and it does so field by field including the easily-missed aspect/picture-shape data. For a zero-parameter read-only list, nothing an agent needs before calling or interpreting results 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; the baseline for a parameterless tool applies. The description correctly spends no words on input syntax and instead spends them on output 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 resource (connected social accounts in this workspace) and enumerates exactly what each entry carries: id, platform, status, limits (text length, hashtags, clickable links) and per-format aspect ratios. The terminology 'channels' vs 'connected social accounts' is reconciled by the mention of channelIds, so an agent knows precisely what it gets back.

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

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

The closing sentence, 'Use the ids as channelIds when creating posts,' gives clear downstream context: call this first to resolve channel identifiers before any post-creation tool. It does not name an alternative or an exclusion, but no sibling tool lists channels, so there is little ambiguity to resolve.

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

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

Annotations only declare readOnlyHint/openWorldHint, yet the description adds substantial behavior: a 50-item page cap, the exact field set with nothing else, exclusion of unsubscribed contacts, cursor/null end-of-list semantics, and a prompt-injection warning to treat contact names as data. That is far beyond 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?

Front-loads 'Read only' and the resource scope, then packs consent semantics, field list, filters and pagination into a few dense but non-redundant sentences. Nothing repeats the schema verbatim and no sentence is filler.

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

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

With no output schema, the description compensates by enumerating the exact returned fields, and it fully documents pagination and filtering behavior for a 6-parameter tool. An agent has everything needed to call it and interpret the response correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains what 'pending' consent actually represents, that the tag may be a name or id, that segmentId comes from postfjord_mail_overview, and that nextCursor must be passed back as cursor. Only the limit parameter is left entirely to the schema.

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

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

States a specific verb and resource ('list contacts') and immediately narrows the scope: only consenting contacts (confirmed, or pending with consent='pending'), never unsubscribed people. The enumeration of returned fields and the max-50 page size make it unmistakable versus siblings like postfjord_add_contact or postfjord_tag_contact.

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 usage context ('Use this to answer questions about the list, not to copy it elsewhere') and routes the agent to postfjord_mail_overview for segment ids. It lacks an explicit when-not-to-use statement relative to other list tools, but the intended call situation is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false; the description reinforces read-only and adds real value: the exact row fields returned (id, channel, preview, unread, tags, waiting, opt-out, 24h window), the 30-per-page cap, and a prompt-injection warning about untrusted names/message text. It stops short of noting cursor lifetime/expiry or behavior when filters match 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?

Front-loaded with scope, then result fields, then filters, then pagination, then a safety note — a logical order. The field enumeration is long but justified because there is no output schema; a couple of clauses could still 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?

With no output schema, the description carries the return shape and does so completely — every row field, ordering, page size, and cursor mechanics — plus an injection-safety note appropriate for externally-authored message 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%, so baseline would be 3; the description goes beyond it by tying channelId to postfjord_list_channels, tying tag to tag names, restating the 30-per-page limit, and explaining that cursor comes from the previous page's nextCursor. It adds cross-tool and pagination semantics 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?

Specific verb and resource ('List inbox conversations / The Inbox: direct message conversations on Instagram, Facebook Messenger and WhatsApp'), plus ordering ('newest first') and scope. It is clearly distinct from postfjord_get_conversation (singular) and postfjord_list_channels (which it references as a lookup source).

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

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

Tells the agent the three filter dimensions (unread, channel id from postfjord_list_channels, tag name) and how to paginate ('pass nextCursor as cursor for the next page'). It does not explicitly say when to prefer this over fetching a single conversation, but the list-vs-get split is implicit and the operational 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so 'Read only' repeats structured data and earns nothing. What does add value is the scope disclosure that drafts are included and the enumeration of returned attributes (status values draft/on/paused, trigger, enrollment and send counts, app-triggerable flag, goal). It still says nothing about pagination, ordering, or result size.

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

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

A single compact sentence with the read-only framing and the resource front-loaded before the attribute list. The attribute enumeration is long but each item tells the agent what it will receive, so it earns its place.

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

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

With no output schema and no parameters, the description sensibly carries the return-field burden, which is the right call. But for a list tool in a suite containing a near-identically named sibling, the missing differentiation and any hint about result volume leave the agent under-informed.

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?

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description does not fabricate any filtering semantics, which is correct given the empty 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?

A specific verb plus resource: list the workspace's email automations, with a clarifying gloss ('welcome emails and other series that send by themselves') and an explicit note that drafts are included. The one gap is that it never distinguishes itself from the sibling postfjord_list_automations, which an agent could easily pick instead.

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

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

There is no statement of when to call this versus postfjord_list_automations, postfjord_get_goal, or the create/set email-automation siblings. 'Read only' implies it is a safe inspection call, but the agent is left to infer that on its own.

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 openWorldHint=false, and the description reinforces rather than repeats them ('Read only'). It adds genuinely new behavioral context beyond the annotations: result ordering ('newest first'), the shape of each record (text, dates, status, plan, what it made, last counted results), and the important caveat that results are 'last counted' rather than live, which the get_goal pointer implies can be stale.

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

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

Front-loaded with the read-only signal and the resource definition, followed by returned fields and then the sibling pointer, so nothing is buried. The parenthetical enumeration of Flow types makes the first sentence dense, but every clause carries information an agent needs.

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

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

No output schema exists, but the description compensates by enumerating the per-record fields and noting the newest-first ordering and the staleness caveat. The main remaining gap is the meaning of the status enum values and no pagination guidance, which matter for a list tool with a capped limit.

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

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

With 50% schema coverage, the schema documents limit ('Default 25') but leaves the status enum undocumented beyond its values. The description adds that status is a filter, but it does not explain what the five status values mean or the practical effect of limit/ordering, so it only partially compensates for the coverage gap.

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

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

States a specific verb+resource and resolves the naming ambiguity by defining Flows as 'goals that became posts, a comment-to-DM automation, a page and welcome emails'. It also disambiguates from the sibling detail tool by naming postfjord_get_goal, so an agent can choose between them 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 to postfjord_get_goal 'for fresh results of one goal', which tells it when this list tool is the wrong choice. It also states the supported filter ('Filter by status') but does not say when filtering is preferable to fetching everything, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real value beyond that with the 'newest first' ordering guarantee and the per-field semantics of status, including that videos lack thumbnails yet. It stops short of describing pagination behavior or what happens when limit is omitted.

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

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

A single dense sentence, but it is front-loaded with the resource and ordering, then flows into the field list and a practical instruction. Nearly every clause carries information; only the parenthetical about video thumbnails is slightly verbose.

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

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

With no output schema and no output annotations, the description carries the entire return-value burden and does so thoroughly: identity, kind, lifecycle status, name, alt text, size, dimensions, duration, and thumbnail availability per media type. Only paging semantics remain unstated, which is a minor gap for a 2-parameter read tool.

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

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

Schema coverage is 50%: status is well documented in the schema itself, while limit has only a min/max constraint and no description anywhere. The description mentions the three status values but frames them as return fields rather than filter semantics, so it does not compensate for the undocumented limit parameter (default value, paging behavior).

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 combination ('Images and videos in the media library, newest first') that is unmistakably a collection read, distinguishing it from the singleton postfjord_get_media without naming it. The returned-field enumeration reinforces the 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?

'Use the ids as mediaIds' implies the downstream workflow (attaching media to posts), which is useful routing context. However, there is no explicit guidance on when to call this versus postfjord_get_media or postfjord_list_* siblings, and no mention of how to widen or page results beyond the limit cap.

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 and openWorldHint, so the bar is lower, but the description adds real value: the hard 30-per-page limit with cursor semantics, and a prompt-injection warning that text/author fields come from outside the workspace and must be treated as information, never instructions. It does not discuss rate limits or failure modes.

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

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

Front-loaded with purpose and scope, then return shape, then filtering, then pagination, then the safety caveat. The long field enumeration sentence is dense but every clause carries information an agent needs to interpret rows.

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

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

There is no output schema, and the description compensates fully by enumerating the return fields (source, link, author handle, text, timestamp, state, relevance, sentiment, intent, one-line summary). Combined with the pagination and injection guidance, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 89%, so the schema already documents limit, since, state, cursor, intent, source, keywordId and minRelevance. The description restates the filter set and clarifies cursor/nextCursor usage but adds no syntax or semantics 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 ('List mentions') and describes the exact object: what people say about the workspace on other sites, from Instagram tags, Google/App Store reviews, Bluesky and Hacker News. It clearly distinguishes itself from get_mention (single mention) and from the other list_* tools by naming the domain.

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 strong operational context: pagination cap of 30 with 'pass nextCursor as cursor for the next page', and the enumeration of filters makes the intended querying use obvious. It stops short of explicitly naming when to prefer this over get_mention for a single item, so it lacks exclusions.

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

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

Annotations already carry readOnlyHint=true and openWorldHint=false, so the 'Read only' opening is redundant, but the description adds genuinely useful behavior: metrics are scoped to the last 30 days, and the state enum is expanded with plain-language meanings (over_plan = published but offline due to plan limits, ended = past liveUntil). Those semantics are not recoverable from the schema or annotations.

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

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

Everything stated is substantive, but the payload is delivered as one very long run-on sentence that mixes three different concerns (page list, workspace address, plan limits, available signup forms and looks). Front-loading 'Read only' is good; the lack of sentence boundaries makes it harder to scan than it needs to be.

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

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

With no output schema, the description carries the return-shape burden and does so thoroughly, including the state vocabulary and the ancillary objects (workspace address, plan allowance, signup forms, looks). The only gaps are pagination totals and failure behavior when landing pages are disabled, both minor.

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

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

Schema description coverage is 100% — limit (default 25, max 50) and offset (chained from nextOffset) are fully documented in the schema. The description adds nothing about pagination or parameter behavior, so the baseline 3 applies.

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

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

The description names the resource precisely (the workspace's link in bio page and landing pages on postfjord.page) and enumerates the exact fields returned, so an agent can distinguish it from postfjord_get_page (single page) and postfjord_create_page. The action verb itself is only implied by the title/name rather than stated in the description body, which keeps it from a 5.

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

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

It states a real precondition — 'Landing pages must be switched on for the workspace' — which tells the agent when this tool will fail. But it never routes the agent to alternatives (get_page for one page, list_signup_forms for the referenced forms) or states when not to use it, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered (the leading 'Read only' is redundant). Beyond that, the description adds genuinely new behavioral facts: the 20-form result cap and the complete shape of what comes back, which is not available anywhere else since there is no output schema.

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

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

Two sentences, front-loaded with the read-only nature and the scope, followed by the field enumeration. The middle field list is dense but each item earns its place because no output schema exists to carry that information.

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

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

With no input parameters and no output schema, the description does the only remaining work: it documents the return fields and the result cap, and explains what the returned ids are used for. An agent has everything needed to call it and consume the result.

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 description correctly implies the absence of filtering or pagination options by describing a fixed workspace-wide result set.

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

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

States a specific verb and resource (list the workspace's signup forms) and bounds the scope with '(at most 20)'. It then enumerates the exact fields returned, so an agent knows precisely what it is asking for and can distinguish it from postfjord_create_signup_form.

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

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

The closing sentence implies the downstream use case ('a form id goes into a landing page form block or an email automation started by that form'), which is helpful chaining context. However, there is no explicit statement of when to call this versus other list tools, and no mention of how the 20-form cap affects callers who expect more.

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 openWorldHint=false, and the description's 'Read only' restates rather than adds to that. What it does add is scope ('every tag in the workspace'), which tells the agent results are not filtered or paginated, but it says nothing about ordering or whether archived tags are included.

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 read-only constraint followed by scope and return fields. The only waste is 'Read only,' which duplicates the readOnlyHint annotation rather than adding new information.

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

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

For a no-parameter, no-output-schema list tool, the description covers what it returns (id and name) and the scope of the result set, which is enough to call it correctly. Only minor details such as result ordering are absent.

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

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

The tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 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 the resource precisely ('Every tag in the workspace') and the returned fields (id and name), so the agent knows it is an unfiltered enumeration. The action verb is only implied by the name/title 'List tags' rather than repeated in the description, and no sibling (e.g. postfjord_tag_contact) is named, so it falls just short of a 5.

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

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

'Tags group contacts; a tag can start an email automation' gives domain context that hints at when tags are relevant (before tagging a contact). However there is no explicit when-to-use, no named alternative such as postfjord_tag_contact, and no stated preconditions, so usage must be 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=true and openWorldHint=false, and 'Read only.' merely restates that. The real added value is the disclosure of what the response contains — including the meaning of the custom 'firstHeard' field and its categories — which the agent would otherwise have to discover empirically, since there is no output schema.

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

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

Information density is high and the routing sentence lands last, but the body is one very long run-on sentence enumerating fields, and the opening 'Read only.' duplicates the annotation rather than front-loading anything new. It is efficient in word count but weakly structured.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so field by field, including the segment shape (id, name, approximate confirmed count) and the firstHeard categories. Only minor gaps remain, such as whether counts are live or cached and what an unconfigured sender state looks like.

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

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

The tool takes zero parameters, so the baseline of 4 applies. No parameter semantics are needed and the description correctly spends its words on return content instead.

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

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

The description names a specific resource — the workspace email overview — and enumerates exactly what it reports: email on/off, sending open, sender readiness, confirmed-subscriber counts, monthly quota, saved segments, and the firstHeard breakdown. That makes it clearly distinguishable from siblings like postfjord_get_analytics or postfjord_list_campaigns. It stops short of a crisp verb-first statement of purpose, leading instead with a return-value inventory.

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

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

The closing sentence, 'Start here before drafting or scheduling an email,' gives explicit positioning in the workflow and implies the drafting/scheduling siblings that follow. There are no stated exclusions or conditions under which to skip it, so it is clear context rather than a full when/when-not matrix.

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: the source post is never modified and a NEW draft is created, nothing is published, the job is async (~1 minute) and must be polled via get_media with status/failed reasons, the workspace quota is 'a few videos a day', and idempotency_key retry semantics are spelled out. These directly support the destructiveHint=false and readOnlyHint=false annotations with real operational context.

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

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

Front-loaded and every sentence is informative, but it is one long run-on paragraph stitched with semicolons and parentheses that makes scanning for a specific rule (still, format, idempotency) slow. A few clauses, such as the repeated restatement of polling and scheduling, could be tightened without losing content.

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

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

With no output schema, the description does the work: it documents the return payload (mediaId, draftId, and still:true/status ready/mediaId for the still case) plus the async lifecycle. Only the rate-limit statement ('a few videos a day') is left vague, which is a minor gap for a tool with this much complexity.

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

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

Schema coverage is 100%, so the schema already carries per-parameter meaning and ranges; the description largely restates it. It does add cross-tool semantics the schema lacks, notably which channels qualify ('formats include reel, video or short' from postfjord_list_channels) and what channelIds falls back to, but most parameter text is redundant with 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 concrete verb and artifact: a 9:16 video (1080x1920, 5-30s, silent) built from pictures with zoom, fades and optional overlay text. It distinguishes itself from siblings by naming postfjord_get_media, postfjord_list_channels and postfjord_schedule_post as separate steps, so an agent knows this tool only builds the draft.

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 input alternatives (postId for a post's pictures/text/fits vs mediaIds for 1-10 library pictures) and explicit output routing (format reel vs story, channelIds override). It also states the one-picture exception (still: true) and the prerequisite flow: poll get_media until ready, get user agreement, then postfjord_schedule_post.

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

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

Goes well beyond the annotations: it declares that nothing is created or sent, only a Flow with status 'proposed'; that unavailable parts are omitted and named in 'missing'; that the workspace AI budget is consumed and the call may take up to a minute; and it spells out retry semantics with idempotency_key. That retry de-duplication does not contradict idempotentHint=false, since each new action needs a fresh key.

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 every block is substantive, but the body is one dense paragraph that blends what the tool does with a long downstream review checklist and launch choreography. The update_goal instruction is stated twice ('write the answers in with postfjord_update_goal' and 'Then change it with postfjord_update_goal'), and the show-the-person enumeration 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 complex generative tool with 8 parameters, nested objects and no output schema, the description supplies what the agent most needs: what gets persisted versus what does not, what the plan contains item by item, what 'missing' means, and the exact next-step tool sequence. Nothing required to invoke it correctly or to handle its result is absent.

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

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

Schema coverage is 88%, so the schema already documents every parameter including the nested offer object and the locale/content-language split. The description adds only indirect mapping ('posts on the goal's dates and channels') without new syntax or constraint detail, so 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 — 'Starts a Flow: one goal that becomes posts, a comment-to-DM automation, a page and welcome emails' — and enumerates exactly what artifacts the plan spans. It is clearly distinguished from single-post siblings and from postfjord_draft_campaign style tools by the 'outcome over days or weeks rather than one post' criterion.

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 trigger phrases ('when the person says "start a flow" or names an outcome over days or weeks rather than one post') with three concrete example utterances, plus named alternatives for the follow-up path (postfjord_update_goal, postfjord_launch_goal). It also states the required review-and-confirm workflow and the 'wait for a clear yes' gate, so when-to-use and when-not are both covered.

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

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

The description adds substantial context beyond annotations: link validity of one hour, per-channel format/shape/mode details, what errors communicates, side effects of generating missing pictures, preview-limit and storage impact, and the read-only key case. These disclosures are important because the tool can trigger picture creation even though the post itself is unchanged.

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

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

The description is dense and front-loads the key point that the post is unchanged, then covers outputs, side effects, and next steps. It is longer than typical but almost every sentence adds actionable information; it could be slightly tighter or better structured but is not bloated.

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 preview tool with no output schema and minimal annotations, the description provides the missing behavioral and output context: per-channel picture details, link expiry, error semantics, rendering guidance, side effects, and alternative-key behavior. An agent has enough information to call and use 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?

There is only one parameter, postId, but schema description coverage is 0% and the description never explicitly explains the parameter's meaning or accepted format. The purpose and context imply it is the post being previewed, so it is usable, but the description misses an opportunity to compensate for the bare schema.

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

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

The description makes clear this is a preview tool that returns the exact pictures per channel without changing the post. It also explicitly distinguishes its role from related siblings like postfjord_schedule_post, postfjord_publish_now, and postfjord_update_post.

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

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

It states exactly when to call it (before scheduling or publishing), what to show the user, how to handle bad crops, and when to re-preview after using postfjord_update_post. It also explains read-only key behavior, giving a complete usage contract.

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 far beyond the annotations: it warns the action is irreversible and hits real accounts, requires user confirmation, explains timeout behavior during multi-minute video publishing, and defines the idempotency_key retry semantics. The annotations only supply generic hints (destructiveHint=false, idempotentHint=false), so this text gives real context about the effects, and the idempotent wording does not contradict the hint.

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 routing rule and the irreversibility warning come first, which is the right order, and almost every clause works for its place. The closing line about failed or partial publishes 'not being kept' is compressed to the point of being hard to parse, which slightly reduces its clarity.

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

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

With no output schema and two parameters, the description carries everything an agent needs: when to call it, the confirmation prerequisite, the timeout and recovery path (postfjord_get_post), and how to retry safely. Nothing required for correct invocation or safe recovery 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?

postId is undocumented in the schema and is only implicitly defined as a post in one of the publishable states. The idempotency_key is described well in the schema, and the description adds the crucial semantics that a retry with the same key returns the first answer and never publishes twice, plus what a same-call-without-a-key counts as. That covers the gap left by 50% schema 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?

The description gives a precise verb and scope: it publishes a post in a named set of states (draft, scheduled, failed, partial) to all its channels immediately. It is unmistakable against postfjord_schedule_post, whose purpose it explicitly contrasts with.

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

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

It states the selecting condition directly: use only when the person wants the post live right now; otherwise use postfjord_schedule_post with a time. It also adds a confirmation precondition and a redirect to postfjord_get_post after a timeout, 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?

Far beyond the annotations, it discloses the full check suite (bracket text, password-request wording, Google Web Risk link checks, plan limits, 20 publishes/hour, workspace-accepted page rules), that nothing is published when a check fails and the answer lists per-block fixes, and scheduled items show at their set time. It also states the permission requirement (a key that may publish) and the idempotent retry guarantee, which is the key nuance the annotations cannot convey.

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

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

Front-loaded with the core publish/unpublish effects before the check and retry detail. The check enumeration is packed into one long sentence, but every clause carries information an agent would otherwise have to discover by failure.

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

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

For a destructive, open-world mutation with no output schema, the description covers what can go wrong (check failures, no partial publish), prerequisites (accepted page rules, publishing key), rate limiting, scheduling interaction, and safe retry. Nothing material is left for the agent to guess.

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?

At 67% schema coverage, the description adds real meaning: the publish/unpublish effect of each action value, and the retry-only semantics of idempotency_key (same key after a timeout returns the first answer rather than acting twice). pageId semantics are left implicit, which is minor since the pattern and required flag are 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?

Both actions are stated with a concrete verb and effect: publish puts the page on the public web at its address or makes the latest draft live, unpublish takes it offline and keeps it as a draft. That distinguishes it cleanly from siblings like postfjord_create_page and postfjord_update_page, which manage content rather than visibility.

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

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

It gives clear operating context: confirm with the owner first, unpublish when the page should go dark but be preserved, and a retry path with the same idempotency_key. It never names a sibling as an alternative (e.g. update_page for edits), so guidance is clear but not a full when/when-not routing.

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

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

Goes well beyond annotations (destructiveHint=false, idempotentHint=false): drafts only, nothing scheduled or sent, AI budget consumption (one AI call per 5 channels), a 12-channel cap, partial-failure behavior, and the timeout/2-minute-wait retry rule. It does not explain what the returned payload looks like, which is a minor gap.

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

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

Front-loaded with purpose and the sibling contrast, and nearly every clause carries operational information. It is a single dense run-on paragraph with semicolon chains, which makes the retry and idempotency rules harder to scan than they should be.

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

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

With no output schema needed, the description covers input choice, cost, concurrency, caps, partial failure, retry timing and idempotency, which is everything an agent needs to invoke this fan-out tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by adding semantics not in the schema, namely the de-duplication rule (channels and the email already having a draft in the group are not written or paid for twice) and a concrete ideaGroupId example. The 12-channel limit and the >5-channel requirement mostly restate 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 outcome ('spread one idea across every channel and email at once') and immediately contrasts it with the single-post sibling postfjord_create_draft. An agent can distinguish this fan-out tool from the create-draft tool 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?

Explicitly says when to use it versus the alternative ('for a single post, write it and save it with postfjord_create_draft') and states the input condition ('Give idea, url, or both'). It also covers the retry path and the add-more-channels path with the same ideaGroupId.

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

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

Adds substantial behavior beyond the annotations: the original is never modified, new files consume plan storage, a per-plan daily resize quota can refuse the call, and the tool briefly waits for a freshly uploaded picture to be ready. Retry semantics with idempotency_key are spelled out, which is important given idempotentHint=false.

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

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

Front-loaded with what the tool does and what it returns, then shapes, then modes, then quotas and retries — a sensible order. The middle section is a dense run-on covering mode/focus/zoom that could be tightened, but no sentence is filler.

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

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

For a mutation tool with no output schema, the description covers output (mediaIds), side effects (storage and daily quota), source-state caveat (waits for upload readiness), and retry safety. An agent has everything needed to invoke it correctly and interpret the result.

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 genuine meaning: at most one of each shape per call, the string form means automatic crop while the object form exposes mode/focus/zoom, and focus is defined as the point that must stay centered. It does not restate the idempotency_key field's own documented behavior, which the schema already covers.

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

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

Specific verb and resource: it makes new resized copies of one media-library picture, one file per shape, and returns mediaIds. It explicitly distinguishes itself from adjacent tools (postfjord_upload_media for the source id, postfjord_get_media for verification, postfjord_make_reel by implication).

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 context: call right after postfjord_upload_media with the new id, check results with postfjord_get_media first. It also gives a concrete decision rule for mode whole (when a crop would cut off heads, hands, feet, or words) versus the automatic crop.

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

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

Goes well past the annotations: irreversible send, workspace send-gate checks, month quota, 'review' status for a large first send, sample-first delivery, A/B split mechanics and the 10-recipient minimum, required permission level, and idempotency-on-retry behavior. This is exactly the additional 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?

Front-loaded with the core action and irreversibility, and most sentences carry unique operational facts. It is long, and the A/B-test paragraph largely rehearses defaults already stated in the abTest schema, which is the main trimmable portion.

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 multi-parameter, high-stakes mutation with no output schema, the description covers preconditions, permissions, irreversibility and retry semantics well. What is missing is what a call returns (scheduled time, campaign id, 'review' status), which the agent needs to confirm success.

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

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

Schema coverage is 80%, so most parameters are already documented. The description still adds meaning the schema lacks: the fallback audience rules ('tags or segment; everyone who confirmed when it has none') and the A/B constraint that each subject must reach at least 10 people. campaignId remains unexplained in both places.

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 ('Schedules a draft email') and immediately scopes it: audience comes from the draft, or one saved segment given here. An agent can tell this apart from postfjord_draft_campaign or postfjord_schedule_post 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 clear operating context: confirm recipients/audience/time with a human first, that sending must be open, content must pass checks, and quota must remain. However it never names alternatives such as postfjord_cancel_campaign or the drafting step, so exclusion guidance is absent.

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 (idempotent, non-destructive, openWorld), it discloses that warnings can be returned, that a warning never blocks the schedule, and what the agent should do with a warning (tell the person, offer fixes). It also states that retries are a no-op and that preview should precede scheduling, which is real workflow context rather than a restatement of idempotentHint.

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 scope and sibling routing, then dry-run, warnings, and picture guidance in a sensible order. Slightly redundant in restating the core action twice ('Puts a time on one draft' / 'Schedules an existing draft at an ISO 8601 date-time') and the picture/fit paragraph is long, but every part carries actionable content.

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

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

There is no output schema, yet the description covers what comes back (warnings) and how to handle it, plus the sequencing with preview_post and dry_run. For a nested-parameter scheduling mutation, an agent has everything needed to call it safely and interpret the result.

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

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

Schema coverage is 75% and the nested fit/aspect docs are already rich, so the schema does much of the work; the description still adds decision value by specifying that scheduledAt needs an offset and by giving a concrete criterion for choosing fit mode 'whole' (cuts through people or words in the picture). It does not explain the 'targets' replacement semantics itself, deferring that to the schema.

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

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

The description opens with a specific verb and resource ('Puts a time on one draft that already exists') and explicitly contrasts it with postfjord_create_draft (new posts) and postfjord_bulk_update_posts (many posts). An agent can choose this tool over its two nearest siblings without opening any schema.

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

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

Gives explicit routing rules ('a new post is made with create_draft, and many posts are moved with bulk_update_posts'), a recommended pre-flight sequence ('Send dry_run: true first', 'Before scheduling, call postfjord_preview_post'), and a conditional remediation path for whole-fit. Nothing about when to use this versus alternatives 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?

Adds substantial context beyond annotations: irreversibility ('cannot be taken back'), the 24 hour window, opt-out exclusion, per-key rate limit, required Publish scope, the side effect of pausing automations in the conversation, and precise retry semantics for idempotency_key. The annotations declare destructiveHint=false and idempotentHint=false; the description's 'cannot be taken back' and retry-key behavior are consistent with those (the key is what makes the retry safe), not contradictory.

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?

Irreversibility and the confirm-first instruction are front-loaded, followed by hard constraints, side effects, auth, and retry guidance in that order. Every sentence carries a distinct, actionable fact with no restatement of the name or 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 an open-world, non-idempotent mutation with no output schema, it covers side effects, preconditions, auth and retry. The only real gap is what the call returns on success (a message id or conversation state), which the agent may need to chain follow-up actions, and no return shape is described.

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 text, conversationId and idempotency_key are already documented in the schema, including the 1000 character cap and the id pattern. The description reinforces the retry use of idempotency_key but adds no syntax or format detail beyond what the schema provides, 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 ('Sends a direct message reply'), scopes it to one Inbox conversation, and anchors it to the product behavior an operator already knows ('the same as Send in the Inbox'), which cleanly separates it from the sibling postfjord_draft_reply. An agent can tell what this tool does without opening the schema.

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

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

Gives real eligibility conditions — only inside the 24 hour reply window, never to an opted-out person, 10 replies/minute per key — and a procedural precondition ('Confirm the exact text with the person you work for before you call this'). It never names the alternative sibling (postfjord_draft_reply) or explicitly says when to prefer it over sending, so 4 rather than 5.

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

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

Annotations already declare the write/idempotent/non-destructive profile, and the description adds the consequence the annotations can't express: turning it on makes the automation start answering people by itself immediately, an outward-facing effect. It also adds an auth requirement (Publish scope) and a human-confirmation norm. It stops short of saying what happens to conversations already in flight or what the call returns.

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, then prerequisites and sibling routing in three short sentences with no filler. The closing "editing is done in the app" is slightly ambiguous in phrasing (editing of what, by whom) but still earns its place as a routing hint.

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 toggle with full schema coverage and annotations covering the safety profile, the description supplies the essential missing pieces: real-world side effect, auth scope, and human-approval expectation. Only the response shape is unaddressed, which is minor absent an output schema.

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

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

Schema coverage is 100%, so both parameters are already documented, including "true switches it on, false pauses it." The description's phrasing echoes that boolean semantics with a little added meaning ("starts answering people by itself right away") but supplies no extra constraints on automationId beyond what the pattern and description already give.

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 ("Switches one DM automation on or off") and the word "DM" disambiguates it from the email-automation siblings. An agent can identify the exact 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?

It gives clear context: confirm with the person first, a Publish-scope key is required, creation belongs to postfjord_create_automation, and editing happens in the app rather than through a tool. What's missing is an explicit exclusion of the near-identical email-automation path (postfjord_set_email_automation), which an agent could plausibly confuse with this one.

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

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

Annotations cover safety (readOnly=false, destructive=false, idempotent=true), but the description adds genuinely non-structured behavior: start runs validation over sender, trigger and every email and reports what to fix, pause leaves contacts paused in place rather than removing them, and the tool needs the Publish scope. That is exactly the kind of pre-flight and side-effect detail annotations cannot express. Missing only error/return shape, which is minor.

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 three actions, then the validation behavior, then the confirmation rule and scope requirement – a sensible order with no filler. The prose is slightly telegraphic ('resume goes on'), but every sentence carries information.

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

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

For a two-parameter mutation with no output schema, it covers the action semantics, the pre-flight validation and its reporting, the confirmation requirement, and the auth scope. An agent could call it correctly and safely from this alone; only the failure/return behavior is left implicit.

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

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

Schema coverage is 50% – automationId is documented there, but the action enum values are not. The description compensates by explaining what each of start/pause/resume actually does to the automation's state and to contacts in flight, which the raw enum 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 the specific resource (an email automation) and the three state transitions it performs, and the first three clauses map one-to-one onto the action enum. It stops short of naming how it differs from nearby siblings like postfjord_set_automation or postfjord_create_email_automation, so an agent must infer the boundary.

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

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

Gives concrete when-to-use semantics per action ('start turns a draft on', 'pause stops sending', 'resume goes on') plus a real procedural constraint: confirm with the person before start or resume. No explicit when-not-to-use or routing to an alternative tool, which keeps it below a 5.

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

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

Beyond the annotations it discloses the side effects that matter: tag creation on unseen names, immediate automation triggering for confirmed contacts, the startsAutomations response field, the required Publish scope, and precise retry semantics. That is substantially more than idempotentHint/destructiveHint already convey.

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

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

Front-loaded with the action, then workflow, return value, auth, and retry in descending order of importance. Dense but every sentence carries distinct operational information.

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

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

No output schema exists, and the description names the meaningful return field (startsAutomations). Auth scope, mutation semantics, confirmation requirement, and retry behavior are all covered, leaving nothing an agent needs 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 only 33% (just idempotency_key), so the description has to carry the rest. It explains tags as names with create-on-new behavior, which is genuinely useful, but says nothing about the 10-tag cap, the 40-character limit, or the email parameter's constraints — all left to the schema.

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

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

Specific verb plus resource plus addressed entity: 'Adds tags by name to the contact with this address.' It also disambiguates the upsert nuance ('A new name makes the tag'), distinguishing it from sibling tools like postfjord_list_tags and postfjord_add_contact.

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 pre-flight workflow: check postfjord_list_email_automations for an automation this tag starts, tell the user, and wait for confirmation. It also states exactly what to do on retry (resend the same idempotency_key).

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: sending 'from' without 'to' moves the whole note while preserving its duration. It does not explain what makes the tool destructive (blanking text), which the schema covers only for 'text'.

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

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

Three short sentences with no filler, and the partial-update rule is front-loaded. The second sentence ('Sending from without to moves the whole note...') is slightly awkward to parse but carries real information, so it earns its place.

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

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

For a 6-parameter mutation with no output schema and a destructive hint, the description covers the trickiest semantic (from/to interplay) but leaves the agent guessing on field-level effects of color/title changes and on what a successful update returns. Adequate but with clear gaps.

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

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

With 6 parameters and only 33% schema description coverage, the description compensates partially by explaining the from/to interaction, which the schema does not. It says nothing about 'color', 'title', or the date format for 'to', leaving several parameters documented only by bare type/pattern constraints.

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