Pith - Instagram Publishing

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

Beyond the annotations, the description discloses that URL sources are mirrored into tenant storage and can expire, that base64 payloads are limited to 8MB decoded, and that sub-720px images are rejected with a user-facing rationale. These are non-obvious behaviors an agent would not infer from readOnlyHint/idempotentHint alone.

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

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

Four sentences, all front-loaded with the primary verb, then alternatives, constraints, and optional usage. There is no filler or redundant restatement of schema fields.

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?

Despite 10 parameters and no output schema, the description supplies the decisive guidance an agent needs to invoke correctly: input mode selection, size/resolution limits, product-shot behavior, and batch filing. The remaining parameters are covered by the schema, and the import workflow does not require a detailed return-value contract.

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 schema coverage already at 80%, the description adds the exclusive-one-of constraint, the decoded size limit, the 720px resolution rule, and the 'source can expire afterwards' reassurance for URL imports. It does not enrich every parameter, but the schema documents those, so the description clearly adds value beyond the schema.

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

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

The description opens with a specific verb and object — 'Import an image into the tenant's asset library' — and the title 'Add a photo' reinforces it. It clearly separates this tool from siblings like delete_asset and download_draft_image by framing the action as ingestion.

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

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

It explicitly tells the agent when to use image_url vs image_base64 ('use when you hold the image and there is no public URL') and mandates exactly one of them. It also gives guidance to send the original rather than a thumbnail or web copy, but it never explicitly contrasts add_asset with sibling tools like curate_images or list_assets.

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 mutation profile and repeat-safety are covered structurally. The description adds the policy that only the owner's explicit choice should drive the call, which is useful context, but it says nothing about irreversibility, what happens to the proposal record after dismiss, or auth requirements.

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

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

Three short sentences, front-loaded with the operation, then the action semantics, then the constraint. No filler and nothing requiring a second read.

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

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

For a 4-parameter mutation tool with no output schema, the definition covers the operation, both action branches, and the source of the ID. It leaves some minor gaps such as the effect of dismiss on the stored proposal and whether an applied drift can be reversed, but the schema already documents the context parameter in depth.

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

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

Schema coverage is only 50% (handle and context are documented; action and drift_id are not). The description compensates by explaining the action enum's meaning ('apply adopts the proposed DNA; dismiss rejects it') and by indicating where drift_id comes from (get_brand_dna), which the bare schema 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 (resolve/apply/dismiss) and resource (a pending Brand DNA drift proposal), and explicitly routes to the sibling get_brand_dna as the source of that pending proposal. An agent can distinguish this from get_brand_dna, refine_brand_dna, and regenerate_brand_dna 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?

Explains the two branches clearly (action=apply adopts, dismiss rejects) and names get_brand_dna as the way to obtain the pending drift_id. The line 'Only the owner's explicit choice should drive this' gives a real usage constraint, though it doesn't state an explicit when-not or a contrary alternative.

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 non-read-only, non-destructive, open-world, idempotent behavior. The description adds meaningful operational detail: the link is one-time, expires in 10 minutes, connects whichever account the user authorizes, and must be displayed verbatim. 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 front-loaded with the main purpose and then flows into trigger, user-facing steps, expiry, and account requirements. Every sentence contributes a distinct operational fact; 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?

Despite no output schema, it tells the agent what to expect (connectUrl), how to handle it, when to confirm via whoami, and the account prerequisite. For a two-parameter tool with a rich schema and strong annotations, nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents both handle and context thoroughly. The description adds the 'no handle needed' clarification, which reinforces the schema, but does not materially augment parameter meaning beyond the structured definitions.

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

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

The description states a specific action ('Get a one-time link') and resource (connects the user's Instagram Business/Creator account to Pith), and explicitly frames it as the prerequisite for publish_post. This distinguishes it from siblings like whoami and publish_post by naming the dependency and trigger condition.

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 call trigger ('as soon as whoami shows no accounts'), says not to ask for a username, and directs the follow-up step (call whoami to confirm). It also states constraints: Instagram professional account required, personal accounts cannot use the publishing API, and the link expires in 10 minutes.

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 mutation, non-idempotent, non-destructive profile, so the bar is lower. The description adds real value beyond them: the reply comes by email, usually within a day, and it imposes a consent constraint ('only send what the user wants sent'). It doesn't warn about duplicate sends given idempotentHint=false, which keeps it from a 5.

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

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

Three sentences, front-loaded with the purpose, then routing conditions, then behavioral expectation. No filler and every sentence carries a distinct load.

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 a fully covered input schema, the description supplies everything an agent needs: purpose, escalation criteria, consent scope, reply channel, and latency. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the strict context-length and third-person rules. The description's consent framing loosely informs the message parameter but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Send a message to a person at Pith on the user's behalf') and explicitly routes away from the list_events sibling by naming it. An agent can distinguish this human-escalation tool from routine data tools without opening a schema.

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

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

Gives concrete when-to-use triggers: something broken list_events doesn't explain, billing/account questions, or an explicit request for a human. It names the alternative (list_events) and the condition that selects it, so the routing decision 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?

Beyond the destructiveHint annotation, the description discloses what gets removed ('Everything else is removed'), what stays aligned ('parallel quality metadata stays aligned'), side effects on drafts ('today's pending drafts are re-seeded'), and a key guardrail ('Refuses to empty the pool'). This is rich behavioral context that annotations alone do not provide.

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

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

Every sentence earns its place: purpose and rationale, what to pass, side effects, and the guardrail. The information is front-loaded with the main action in the first sentence and no filler or repetition of schema 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 destructive tool with 3 parameters, 100% schema coverage, and no output schema, the description fully covers inputs, effects, constraints, and safety behavior. Nothing an agent needs to invoke it correctly or anticipate consequences is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by clarifying that mixing URL and scraped:N id formats is fine and specifying exactly where each comes from (get_tenant and list_assets). This helps the agent construct the 'keep' parameter correctly beyond the raw 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?

The description clearly states the verb and resource: 'Trim the scraped Instagram photo pool to the entries worth generating from.' This distinguishes it from sibling tools like delete_asset by focusing on curation of the pool rather than deleting individual assets, and explains the rationale ('off-brand photos in the pool produce weird stories').

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

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

The description gives clear context for when to use the tool: when the scraped pool contains off-brand photos and needs to be narrowed to generation-worthy entries. It does not explicitly name alternatives like delete_asset or state when not to use this tool, but the selection criterion 'worth generating from' is enough to guide an agent.

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

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

The destructiveHint annotation already marks this as a destructive operation, and the description reinforces that by saying 'Remove'. It adds useful context beyond the annotation by defining the scope of what can be deleted and excluding the scraped pool, which is a valuable behavioral boundary.

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

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

The description is a single, focused sentence with no filler. The main purpose is front-loaded, and the exclusion/alternative is attached efficiently without redundancy.

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

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

For a straightforward deletion tool with destructiveHint true, the description sufficiently describes the intended use, the boundary of what it can operate on, and the alternative for the exception case. There is no missing information an agent needs to select and invoke it correctly.

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

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

Schema description coverage is 67%; context and handle are already well documented in the schema, while asset_id lacks a description. The description partially compensates by clarifying asset_id as an uploaded asset and explicitly excluding scraped entries, giving extra meaning beyond the schema.

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

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

The description clearly states the action ('Remove an uploaded asset') and the resource ('from the library'), and it distinguishes itself from sibling tools that handle scraped assets. The parenthetical about scraped:N entries immediately differentiates it from curate_images, so an agent can tell them apart without opening schemas.

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

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

The description explicitly states when not to use this tool: scraped entries cannot be deleted here and should be handled by curate_images. It names the alternative and the condition for selecting it, providing crisp routing guidance.

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

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

The description goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing that the first call per draft counts toward the Free monthly AI-stories cap, that re-fetching published/downloaded drafts is free, and that a cold render takes 60-90 seconds. These quota and latency facts are exactly the non-obvious behaviors an agent needs and are not derivable from annotations or schema.

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

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

Three sentences, each earning its place: purpose first, then quota behavior, then latency. No filler, no repetition of schema content, and the most decision-relevant fact (cap counting) is front-loaded immediately after the purpose.

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

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

For a 3-parameter, no-output-schema tool, the description covers purpose, cost/quota behavior, and latency — the critical operational facts. Minor gaps remain: the exact return shape (though 'resolve URL' implies the output) and the undocumented draft_id parameter. These are small enough that the tool is still safely callable by an agent.

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 67%, with handle and context well-documented in the schema itself; the description adds no parameter-level meaning on top. The required draft_id parameter has no schema description and the tool description does not compensate for it, though its meaning is largely self-evident from the name.

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 ('Resolve') and resource ('the rendered story image URL'), and frames the use case as 'for save-and-post-yourself,' which is clear. It does not explicitly name a sibling alternative, so an agent must infer the distinction from get_draft or publish_draft, but the 'story image' + 'manual posting' phrasing makes the scope reasonably 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 'for save-and-post-yourself' implies this tool is for manual posting rather than automated publication, which is arguably contrasted with siblings like publish_draft. However, there is no explicit when-to-use, when-not-to-use, or named alternative, so the guidance is implied rather than stated.

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

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

With destructiveHint=true and openWorldHint=true already declared, the description goes well beyond them: remove is a soft-delete, add/update return a `warnings` field when a post will not go out (stories cap, vacation mode), scheduling can be refused with scheduling_not_available, and the approval semantics of auto/warning constitute the owner's consent. This is exactly the extra behavioral context annotations cannot convey.

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

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

It is long but front-loaded with the action enumeration, and most sentences carry operational facts (timezone, slide limits, warning triggers, consent semantics) rather than filler. The approval_mode paragraph is dense but each clause adds a distinct behavior; it could still be tightened slightly.

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

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

For a 15-parameter, no-output-schema mutation tool the description covers the high-stakes behavior (action semantics, approvals, refusals, warnings, date format) that an agent needs before calling. It remains incomplete on several lower-traffic params (caption_mode, beat_slug, source_asset_id) and does not restate the return shape beyond `warnings`.

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% across 15 params, so the description must compensate, and it does for the critical ones: it spells out scheduled_date format/timezone/default publish time, the 2-10 carousel slide constraint, all three approval_mode enum meanings, recurrence in update, and days for bulk_fill. Gaps remain for caption_mode, beat_slug, source_asset_id, and video_url, which are undocumented 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?

The description names a specific verb+resource ('Manage scheduled posts') and then defines each of the four action values distinctly (add creates, update patches, remove soft-delete cancels, bulk_fill generates AI drafts). An agent can tell this apart from read-only siblings like get_schedule or the publish_draft path mentioned inside the text.

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

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

It gives clear conditional guidance for approval_mode ('Set auto or warning only when the owner asked for it') and names the alternative flow ('pass approval_mode=email to have it wait for the owner's explicit publish_draft call'), plus the refusal condition for accounts without timed publishing. However it never disambiguates edit_schedule from siblings like update_draft or generate_draft, which also touch drafts.

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

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

Annotations declare destructiveHint and idempotentHint, and the description adds real context beyond them: gap-filling idempotency that leaves decided drafts untouched, the destructive semantics of force, the slot-scoping side effects, and a cost warning ('SLOW: each draft is 1-3 LLM calls'). This is unusually rich behavioral disclosure.

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

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

Front-loaded with the primary action, then escalating detail on idempotency, force, slot_index, and cost. Four dense sentences, all earning their place, though the density slightly hurts scannability.

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

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

For a destructive, non-read-only, SLOW tool with no output schema, the description covers safety, idempotency, cost, and scoping well. It omits return shape and failure handling, but those are secondary given the annotations already signal mutation.

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

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

Schema coverage is already 80%, so the baseline is 3, and the description earns above that by explaining force ('wipes today's PENDING drafts first'), slot_index ('targets ONE slot of a configured asset flow', with named flow types), and the idempotent re-run behavior. It does not clarify handle or beat_slug beyond the schema.

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

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

The description gives a specific verb and resource ('Run the daily draft engine now: generates today's pending drafts for the active flow') and scopes it precisely. It implicitly separates itself from siblings like regenerate_draft and list_drafts by defining exactly what gets generated and when.

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 clear contexts: run for the day's drafts, use force to wipe today's pending drafts first, and use slot_index to re-fire one failed slot 'without regenerating the day'. It stops short of naming an explicit alternative (e.g. regenerate_draft) or stating when NOT to call it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds interpretive value beyond those annotations: it enumerates the returned fields (subscription state, plan, payment-method presence) and clarifies that 'none' is a legitimate free-tier state, not an error. It does not address auth, rate limits, or error behavior, but for a read-only status lookup the added context is meaningful.

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

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

The description is two short sentences: the first front-loads the returned fields, and the second clarifies an important edge case ('none' means free, not broken). Every word earns its place, with no filler or repetition of the schema.

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

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

This is a simple read-only status tool with two fully documented parameters and no output schema. The description covers the essential return semantics and explicitly addresses a potentially confusing state. The required context parameter's unusual formatting requirements are fully carried by the schema, so nothing needed for correct invocation 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%: both 'handle' and 'context' are already explained in detail in the input schema. The tool description adds no parameter-specific guidance, so the baseline of 3 applies. It neither repeats nor contradicts 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 specifies the resource (the account's subscription state) and the exact output contents: active/cancelled/none, the plan, and whether a payment method is on file. The title 'Get billing status' reinforces the action. No sibling tool covers the same concern, so it is unambiguously distinguishable.

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 provides no guidance on when to use this tool versus alternatives. It does not mention sibling tools such as get_checkout_url, nor does it state when not to call it. The note about 'none' is an interpretation aid, not tool-selection 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 destructiveHint=false, covering the safety profile. The description adds the behavioral detail that a pending drift proposal is included, which is not implied by annotations. It clarifies that the tool returns background-detected updates awaiting owner approval. This goes beyond the annotation baseline.

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

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

The description is two concise sentences, front-loading the core purpose and immediately following with the drift-proposal detail. Every word earns its place, with no redundancy or filler.

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

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

For a read-only retrieval tool with no output schema, the description gives a sufficient inventory of what is returned (identity, voice, palette, beats, drift proposal). It does not describe return formatting or error conditions, but these are minor for a simple getter. The lack of an output schema is partially mitigated by the content list.

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

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

Schema coverage is 100%, with both handle and context parameters well-described in the schema. The tool description adds no additional parameter semantics beyond what the schema already provides. Baseline 3 is appropriate since the description does not need to compensate for schema gaps.

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

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

The description clearly identifies the tool as retrieving the tenant's Brand DNA — a specific resource — and enumerates its contents (identity, voice, palette, posting beats). It also mentions the pending drift proposal, which distinguishes it from modification tools like refine_brand_dna or regenerate_brand_dna. The purpose is unambiguous.

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

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

The description states this is the 'single source of truth every draft is generated from,' implying it should be consulted before draft generation. It does not explicitly contrast with siblings like brand_dna_drift, but the inclusion of the drift proposal suggests how to handle pending updates. It provides contextual guidance without explicit when-not-to-use.

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 a crucial behavioral guarantee beyond the annotations: the tool never charges on its own and payment only occurs if the user completes checkout. It also clarifies that the returned URL is for the user to open, which is useful for agent decision-making.

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-load the action and result, then add a critical safety clarification. 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?

The description covers the action, the return value (URL), and the main side-effect boundary (no automatic charge). It leaves parameter details to the schema, but is otherwise sufficient for a focused checkout-link 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?

With schema coverage at 50%, the description needed to compensate for plan and interval semantics, but it only refers generically to a 'plan upgrade.' It does not describe the interval choices, defaults, or the required context parameter's constraints.

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 and resource: it creates a hosted checkout session for a plan upgrade and returns its URL. This clearly distinguishes the tool from billing/status and asset-management 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?

The intended use is implied by 'for a plan upgrade' and the payment note, but there is no explicit statement of when to choose this over alternatives or when not to use it. No sibling is named or contrasted.

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 valuable non-obvious behavior beyond the annotations: setting include_image_url=true can trigger a cold render that calls the image model and takes 60-90 seconds. The readOnlyHint and destructiveHint annotations only cover safety, not latency or model invocation, so this is genuine added context with no contradiction.

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

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

The description is two focused sentences with no filler. The core purpose is front-loaded, and the conditional behavior and critical warning are packed efficiently into the second sentence.

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

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

For a single-object read tool, the description covers the essential behavior and the trickiest caveat (image render latency). There is no output schema, so 'full detail' gives a general sense of the return payload but not an explicit shape. The required context parameter is well handled by the schema, so this is reasonably 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?

The schema already documents draft_id, handle, context, and include_image_url. The description enriches include_image_url by explaining the render/cached-render distinction and the cold-start latency, which is not in the schema. With 75% schema coverage, this pushes parameter semantics above the baseline.

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

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

The description opens with a specific verb and resource: 'Fetch one draft in full detail.' It immediately distinguishes this from list_drafts (plural listing) and update_draft/publish_draft. The optional image-render behavior is also clearly tied to the tool's purpose.

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

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

It establishes a clear context: use when a single draft's full detail is needed, optionally with the rendered story image. However, it does not explicitly name alternatives such as list_drafts or download_draft_image, or state when not to use this tool, so it stops short of the highest bar.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond these: the response includes the full flow catalog for reference, and covers not just the active flow but also its config, readiness, and decision history. This helps set expectations for what the read operation 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?

Two sentences with no filler. The core purpose is front-loaded in the first sentence, and the second sentence adds the catalog detail. Every word earns its place.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so by enumerating: active flow, config, readiness, decision context, and full catalog. This is largely complete, though it doesn't explain concepts like 'readiness' or 'decided' in depth, which is acceptable for a read-only informational tool.

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

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

Schema description coverage is 100%, and both parameters (handle and context) are already well documented in the schema. The tool description doesn't add parameter-specific guidance, so the baseline of 3 applies.

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

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

The description states exactly what the tool returns: which of five named flows is active, its config, readiness, and decision details, plus the full flow catalog. This is a specific, resource-focused purpose that clearly distinguishes it from sibling tools like set_flow or get_schedule.

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

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

The description makes the use case obvious: when an agent needs to know the tenant's active daily content flow, its configuration, or readiness. It doesn't explicitly name alternatives or exclusion conditions, but the specificity of the content loop and flow names leaves little ambiguity.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, so the safety profile is covered. The description adds real behavioral context beyond that: UTC instants with tenant timezone for display, ordering, rejection filtering, and what each per-item verdict (capVerdict, scheduledPublishFailedReason, waitingForTap, notices) means. It stops short of pagination, size limits, or empty-result behavior.

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

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

Purpose, ordering, and exclusions are front-loaded in the first sentence, and the second sentence is devoted to return-field semantics. The trailing clause chain ('and waitingForTap ... and notices ...') is slightly run-on, but with no output schema every clause earns its place.

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

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

With no output schema, the description correctly carries the return-value burden by explaining every notable field and the timezone convention. It is nearly complete for a read-only list tool; only pagination and empty-state behavior are unaddressed.

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

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

Schema description coverage is 100% and the schema fully documents handle (with/without @, omit for default) and the context parameter. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('List every draft with a scheduled publish time') plus two scoping rules: soonest-first ordering and exclusion of rejected drafts. An agent can distinguish this from list_drafts or get_draft without opening any schema.

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

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

The exclusion of rejected drafts and the ordering hint at when this view is appropriate, but there is no explicit when-to-use statement and no named alternative (e.g., list_drafts, edit_schedule, get_draft). Usage is implied rather than stated.

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

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

Annotations already mark the tool readOnlyHint and non-destructive. The description adds a useful behavioral caveat: both include_drafts and include_scraped_images can be large, implying potential payload/performance cost. This goes beyond the structured annotations without contradicting them.

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

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

Two efficient sentences. The first front-loads the returned profile fields; the second gives a crisp, actionable warning about the optional large includes. There is no filler or repetition of schema 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's field list substitutes for return-value documentation fairly well. It covers the main data categories and flags the cost of optional includes. It stops short of describing exact response shape or edge cases, but the schema fully documents the required context 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 100%, so the baseline is 3. The description adds decision-relevant meaning by explicitly warning that the two boolean include parameters can return large data, helping agents avoid expensive calls unnecessarily.

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

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

The description clearly says 'Fetch a tenant's profile' and enumerates the exact contents: brand DNA, active flow + config, Instagram connection state, automation settings, and timezone. This distinguishes it from narrow siblings like get_brand_dna or get_flow by scope, though it does not explicitly name those alternatives.

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

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

No explicit when-to-use vs alternatives is provided. The agent must infer that get_tenant is the umbrella profile fetch because siblings like get_brand_dna and get_flow exist. The only direct usage guidance is the warning to use include_drafts/include_scraped_images sparingly.

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

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

Annotations already establish read-only and non-destructive behavior, and the description adds substantial operational nuance: the rolling 30-day window, that published OR downloaded stories both count, that BYO/publish_post posts never count, and that resetAt is authoritative rather than calendar months. These are exactly the non-obvious behaviors an agent must know.

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

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

The description is dense but efficient: no filler, and the most important scope ('Plan tier plus metered usage') is front-loaded. The long comma-separated list could be more scannable, but every sentence earns its place.

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

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

With no output schema, the description carries the burden of explaining what the tool returns, and it covers plan tier plus all metered fields and key counting rules. It could be more complete about response shape or value formats, but an agent has enough to invoke 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 description coverage is 100%, including a detailed instruction set for context, so the baseline applies. The description does not add anything about the handle or context parameters; it only describes the output domain.

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

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

The description states a specific verb ('get') and resource ('plan usage'), then enumerates exactly which metrics are returned: AI stories, reels budget, BYO publishes, and publish streak. It is unmistakably about usage rather than generic tenant info, though it does not explicitly distinguish itself from the sibling get_billing_status.

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 content implies the tool is for checking plan tier and metered usage, and the caveat about resetAt tells the agent not to assume calendar months. However, it gives no explicit guidance about when to prefer this tool over related siblings like get_billing_status, and no when-not-to-use 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context beyond that: the list mixes recent uploads with scraped Instagram images, scraped ids follow a recognizable pattern, and the default 12 only shows the freshest uploads. It also discloses that deletion is limited to uploads only. This goes beyond the annotation baseline and conveys useful operational behavior.

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

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

Three sentences, each earning its place: the first defines what is listed, the second tells how ids are used downstream, and the third gives parameter guidance. The most important scoping statement is front-loaded, and there is no filler or repeated schema 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?

For a straightforward list tool with no output schema, the description covers the composition of results, id format, downstream consumers, and limit behavior. It does not spell out the full return shape or ordering, but the absence of an output schema is partly mitigated by the explicit id-pattern example and the "freshest uploads" ordering clue. Overall it gives an agent enough to call and interpret the result correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds value by connecting the limit parameter to a real use case: "Raise limit (≤100) when auditing a large campaign pool — the default 12 shows only the freshest uploads." It also clarifies that scraped images are always included regardless of limit, reinforcing the schema note. This is more than a restatement of parameter names and defaults.

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

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

The description clearly states the tool lists "the tenant's pickable images" and specifies the two sources: recent uploads plus the scraped Instagram portfolio. It also gives concrete id examples like "scraped:3", so an agent immediately understands both what is returned and how asset ids are formatted. This is a specific verb-plus-resource statement that does not merely restate the title.

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

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

The description gives actionable usage context: asset ids from this tool feed manage_product, edit_schedule, set_flow campaign_asset_ids, or delete_asset, with the caveat that delete_asset is uploads-only. It also explicitly tells the agent when to raise the limit: when auditing a large campaign pool. It does not formally name an alternative tool to use instead, but the practical when-to-use 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 destructiveHint=false. The description adds useful behavioral context beyond that: newest-first ordering, the meaning of pending status, and the difference between summary and full output, including that full output exposes every column except secrets. Pagination or empty-result behavior is not disclosed, but the added details are meaningful.

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 carry substantial information with no filler. The core purpose and ordering are front-loaded, followed by the most decision-relevant filtering and verbosity details. Every clause earns its place.

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

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

For a read-only list tool with 5 parameters and no output schema, the description provides enough for an agent to call it correctly: scope, ordering, status semantics, and output verbosity behavior. Parameter requirements beyond this live in the schema, and the description does not need to repeat them.

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

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

The input schema documents handle, status, and verbosity enums, but the description enriches semantics by explaining what 'pending' means and what each verbosity level returns. This goes beyond the schema's enum names. Limit and handle are not discussed in the description, but the schema covers their defaults and constraints, so the overall parameter guidance is strong.

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

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

The description states a specific verb and resource: 'List story/post drafts for an account, newest first.' This clearly distinguishes the tool from siblings like get_draft (single draft retrieval), generate_draft, and update_draft. The mention of account scoping and ordering adds precision beyond the title.

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

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

The description gives actionable context: status filtering is explained ('pending = awaiting your approve/reject') and verbosity options are tied to decision-making ('summary returns the fields needed to decide'). It does not explicitly name alternatives or state when not to use this tool, 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 mark this as read-only and non-destructive. The description adds beyond that by revealing the newest-first ordering, the event categories covered, and the optional exact-match filter. It does not contradict annotations, and the added behavioral detail is useful for interpretation.

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

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

The description is compact and front-loads the core identity ('event-log tail, newest first') before adding use cases and constraints. Every sentence contributes: purpose, when to use, and parameter caveats, with no filler.

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

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

For a read-only list tool with well-documented parameters and clear annotations, the description covers the essential context: ordering, event types, and triggering scenarios. It doesn't describe the return shape, but no output schema exists and the tool's purpose is straightforward enough that this is not a significant gap.

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

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

Schema description coverage is 75%, so the baseline is 3. The description mostly repeats what the schema already states: optional exact event filter, limit ≤ 200, and example event names. It adds little meaning beyond the structured parameter descriptions for handle and context.

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

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

The description states a specific verb and resource: it lists the tenant's event-log tail, newest first, and clarifies its role as the source of truth for why events happened. It also distinguishes itself from sibling tools by tying usage to generate_draft failures and scheduled publish misses, so an agent can tell it apart from list_drafts or get_schedule.

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 explicitly says to use this tool when generate_draft came back empty or a scheduled publish didn't land, giving clear contextual triggers. It does not name alternative tools for other situations, so it lacks explicit when-not-to-use guidance, but the context is strong enough for selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is not burdened with basic safety disclosure. It adds useful scoping ('active products', 'attached photos') and relationship to the daily-products flow but does not cover ordering, pagination, or authentication behavior.

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

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

The description is a single front-loaded sentence that conveys scope, included data, and business context without filler or redundancy.

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

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

For a simple read-only listing tool with full schema parameter coverage and annotations, the description gives enough context to select and invoke it. It could be slightly stronger by explicitly saying it returns the full active product set, but the 'pool' phrasing reasonably implies that.

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?

Both parameters (handle and context) are fully documented in the JSON schema with 100% coverage, so the description is not required to add parameter-level details. It offers no extra semantic value for the parameters, matching the baseline for high 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 clearly scopes the tool to active products with their attached photos and ties them to the daily-products flow, making it distinct from general asset or draft listings. It does not explicitly name sibling tools or include a full sentence with an action verb, though the title supplies the 'list' action.

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

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

The 'pool the daily-products flow draws from' clause gives a concrete usage context for when this read-only listing should be consulted. It does not name alternatives or state when not to use it, so it stops short of full guidance.

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

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

Annotations already flag destructiveHint=true, but the description adds real context beyond them: archive is a soft delete that also drops the product from the flow pool, empty string clears description, and price -1 clears price. It stops short of stating reversibility or permission requirements, but the added behavioural nuance is substantive.

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

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

Front-loads the purpose, then packs action semantics into compact parentheticals with no filler sentences. The dense run-on style is slightly hard to scan 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 9-parameter, 7-action destructive tool, the description covers actions, parameter combinations, and clearing/soft-delete semantics. No output schema exists and return behaviour is not described, and permission/auth requirements are unstated, but overall an agent has enough to invoke 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?

With only 22% schema coverage, the description carries the load and does so well: it maps name/product_id/description/asset_id/price/currency to their respective actions, explains price is in major units ('82 for ₪82'), currency defaults to ILS, and documents the empty-string and -1 clearing conventions.

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 ('Product CRUD for the daily-products flow') and then enumerates all seven discrete actions, so an agent can immediately tell this is the mutation counterpart to list_products. Sibling differentiation is implicit through the action list, which covers create/rename/archive/photo/description/price operations none of the read tools provide.

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 per-action parameter mapping effectively tells the agent which action to pick for a given goal, and 'asset_id from list_assets' explicitly routes to a sibling tool. It lacks explicit exclusions (e.g. 'use list_products to read'), 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 mark it destructive, idempotent, and open-world, and the description adds exactly the context those hints can't: the 60-120s runtime, safe-retry-on-timeout semantics, the 24h scrape cache, and the refusal rule for handles already owned elsewhere. This is precisely the behavioral detail an agent needs before invoking an expensive mutation.

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

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

Front-loads what it does, then runtime/retry behavior, then the follow-up workflow — a sensible ordering. It is dense and runs long, but nearly every sentence (timeout retry, cache, ownership refusal, curation step) carries operational value.

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 slow, destructive, no-output-schema onboarding tool, the description covers duration, idempotent retry, ownership refusal, and the exact next steps. Nothing an agent needs to call and chain this tool correctly is missing.

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

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

Schema coverage is 100%, so handle, context, and force are already documented in the schema; the description adds only marginal detail on force ('re-derive DNA + photos') beyond the schema's own text. Baseline 3 is appropriate when the schema carries the parameter 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+resource ('Create and link a NEW pith.day account from a public Instagram handle') and enumerates the concrete pipeline steps it performs. It clearly distinguishes itself from siblings like connect_instagram and refresh_scrape by claiming to be the only tenant-linking tool.

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 conditions (public handle, new account, refuses handles owned by another tenant) plus a full post-return workflow (curate_images, get_flow/set_flow). It does not explicitly compare against connect_instagram or refresh_scrape for the case of an existing tenant, which is the one remaining ambiguity.

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

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

Beyond the annotations (destructiveHint=true), the description discloses the full pipeline: payment gate, monthly AI-story cap, publish lease preventing double-posts, and retry with backoff. It also flags refused scheduled drafts. This gives the agent a solid understanding of side effects and constraints.

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-load the core action and immediately follow with prerequisites. Every clause carries relevant information—null, no filler. The structure makes it easy to scan.

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

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

The description covers prerequisites, exclusions, and pipeline behavior, which is sufficient for a tool with 3 simple parameters and no output schema. It doesn't describe the success response, but that is not typically required when no output schema is present. It is slightly less complete than a perfect definition because it could mention what happens on success, but the overall context is strong.

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 schema coverage at 67%, the description adds important semantics to draft_id by requiring it to be an approved draft and forbidding scheduled drafts. The schema already describes handle and context, so the description's incremental value is concentrated on draft_id, which elevates it above a pure baseline but not to full coverage for all parameters.

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

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

The description states a specific verb ('Publish'), a specific resource ('draft to Instagram'), and a clear scope ('ONE approved or edited draft right now'). It distinguishes from siblings by emphasizing the draft pipeline and prerequisites, leaving no ambiguity about what the tool does.

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

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

It explicitly tells the agent when to use this tool vs alternatives: 'use update_draft first' for approval, and 'a scheduled draft is refused (the scheduler owns it, unschedule first)' as a clear exclusion. This is precise when-to-use guidance.

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

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

Goes well beyond the annotations: plan quota accounting (5/30 days on Free, shared with AI stories and scheduled posts), the appended '✨ Posted with pith.day' branding line and how to detect it via finalCaption, story caption behavior, and a detailed idempotency/timeout recovery contract (same key or draft_id never double-posts). This is unusually rich behavioral disclosure for a mutation tool.

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

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

Front-loads the core action and then layers constraints in a logical order (quota, branding, connection, retry, scheduling). Dense and largely waste-free, though the plan-quota and branding details make it longer than strictly needed to invoke the tool correctly.

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, yet the description still tells the agent where to confirm the final posted caption (response.finalCaption) and how to recover from timeouts. Prerequisites, side effects, and retry semantics are all covered, so nothing needed for a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning on top: it explains the retry relationship between idempotency_key and draft_id and clarifies that captions are posted verbatim and ignored for stories, which the schema only hints at.

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

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

States a specific verb (publish) plus resource (image(s)+caption to Instagram) and enumerates the three supported output shapes (story, feed, carousel). An agent immediately knows what the tool produces and at what scope, without needing the schema.

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

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

Gives clear conditions: posts go out immediately, scheduling is explicitly not supported here, and a connected account is required via connect_instagram. However it never names publish_draft, the obvious sibling for publishing an already-generated draft, leaving the agent to infer which of the two to pick.

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

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

Goes beyond the annotations by disclosing the default persistence behavior ('otherwise the change is persisted immediately') and the non-saving escape hatch via preview_only=true, which is exactly the destructive semantics flagged by destructiveHint=true. It still omits permission requirements, reversibility, and whether an existing Brand DNA must already exist.

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

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

Two dense sentences with the core capability front-loaded and the persistence/preview distinction saved for the second sentence. The inline examples earn their space by showing the expected input style.

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, it covers the critical behavior (immediate persistence vs preview) and input expectations. It does not describe what the non-preview call returns or any prerequisite state, which is a modest remaining gap.

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

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

Schema coverage is 75%, and the description supplies the missing semantics for preview_only (true = returns patch without saving, false = persists). It also illustrates the kind of free-text value 'message' expects, though handle and context carry no additional explanation beyond the schema.

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

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

States a specific verb and resource ('Brand DNA editor') and qualifies it as the chat-tuned variant, which implicitly separates it from get_brand_dna and regenerate_brand_dna. The concrete example phrases ('warmer voice', 'switch palette to sage green') make the operation 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?

Clearly conveys the usage context: describe a desired change in plain language and the LLM produces a validated patch, versus other Brand DNA tools that read or fully regenerate. It gives input examples and explains preview_only, but never explicitly names an alternative tool or a when-not-to-use condition.

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

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

Annotations already signal destructive and non-read-only behavior, but the description adds essential context: only the photo pool is replaced, while brand DNA, flow, and drafts are untouched. It also discloses timing and quota limits, giving the agent a clear picture of side effects.

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

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

Two compact sentences front-load the main action and effect, then add scoping and operational constraints. Every clause contributes value with no redundancy or 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 state-changing refresh tool, the description covers what changes, what is preserved, runtime, and quota. Combined with full schema documentation and annotations, an agent has all necessary information to invoke it correctly without 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 description coverage is 100%, so both parameters are already fully documented. The description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Re-run the Instagram scrape' and 'replace the tenant's photo pool'. It clearly distinguishes this from related siblings like curate_images or refresh_website by describing the mirroring behavior and explicit scope boundaries.

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 provides a clear situational trigger ('my IG grid changed, pull the new photos') plus practical constraints like runtime and free-tier quota. It does not explicitly name alternative tools or exclusion conditions, so it falls just short of full routing guidance.

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

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

Annotations already indicate idempotent, non-destructive, and open-world behavior. The description adds meaningful behavioral detail beyond those flags: the 24-hour cache window, the 'cached' status behavior, server-side processing after timeout, and per-product persistence. It does not overstate side effects and matches the 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?

Three dense sentences cover the pipeline, caching semantics, and timeout behavior without filler. The most important action and scope are front-loaded, and every sentence adds operational value. Minor formatting awkwardness ('returns status:"cached"') does not harm 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?

The description provides enough to decide when and how to call the tool and what to expect on cache hits or timeouts. However, with no output schema, it does not describe the shape of a successful first-run response or how the caller should retrieve the persisted per-product results, leaving some ambiguity for an agent.

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

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

Schema description coverage is 100%, so both 'handle' and 'context' are already documented in the schema. The tool description adds no parameter-specific meaning beyond the schema, which is acceptable at baseline but not elevated.

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 action ('Crawl the tenant's website and run the enrichment pipeline') and enumerates concrete pipeline stages: Brand-DNA facts, product import, and site-image candidates. It clearly identifies the resource (tenant website) and the operational scope, though it does not explicitly contrast with nearby siblings like refresh_scrape or set_website.

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

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

The description gives practical call guidance: re-crawls are cached for 24h, repeat calls return 'cached' without spending a crawl, and long sites keep processing server-side if the call times out, so the agent should call again. It lacks explicit comparison to alternative tools, but the context for calling and retrying 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 flag destructiveHint=true, but the description goes further by naming exactly what is lost ('REPLACES the current DNA'), quantifying the cost ('SLOW (60s+)'), and imposing a human-confirmation gate before the destructive write. That is precisely the behavioral context annotations cannot express.

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

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

Three tight sentences, front-loaded with the action, then the cost, then the routing advice. No filler and nothing an agent must read twice.

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, long-running, no-output-schema tool the description covers impact, latency, and the confirmation requirement. The only minor gap is whether the 60s+ call blocks or runs asynchronously, which an agent might want to know before sequencing other calls.

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

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

Schema description coverage is 100% — the handle and context parameters are fully documented in the schema, including default-account behavior and the 15-25 word third-person constraint on context. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (re-scrape and re-derive) on a named resource (the tenant's Instagram / Brand DNA) with the distinguishing detail 'from scratch'. This clearly separates it from refine_brand_dna and refresh_scrape, so an agent can pick 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?

Explicit routing: 'Prefer refine_brand_dna for adjustments' names the alternative and the condition that selects it, and 'confirm with the user before calling' states a required precondition. Both when-to-use and when-to-avoid are covered.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is partially covered. The description adds genuine value beyond that: it discloses that the draft is reset to pending, its cached render is invalidated, and the per-tier rate limits (1/day Free, 5/day Pro). It does not say whether the prior text is recoverable or what happens when the cap is exceeded.

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 tightly packed sentences with zero filler; the core operation and its side effects lead, and the rate limits close the sentence as supporting constraint. Every clause earns its place.

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

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

For a mutation tool with instructive annotations and no output schema, the description covers the key behavioral facts an agent needs (text replaced, status reset, cache invalidated, caps). It stops short of stating recovery behavior, cap-exceeded handling, or the handle parameter's role.

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%; the context and handle parameters are documented in the schema, while angle and draft_id are not. The description clarifies that angle is optional steering and hints at draft_id's role, but adds no semantics for handle and no detail on how angle values map to output. Only partial compensation for the coverage gap.

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

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

The description states a specific verb+resource: re-drafting an existing draft's story text, optionally with an angle. The phrase 'one draft's story text' and the reset-to-pending side effect clearly distinguish this from generate_draft (new) and update_draft (field edits).

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 implies usage through the tier cap ('Free 1/day per draft, Pro 5/day'), which tells the agent this is a rate-limited operation, but never states when to prefer this over update_draft or generate_draft, nor any exclusions. Usage context is inferable but not explicit.

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

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

Annotations declare a non-read-only, idempotent, non-destructive update, and the description goes well beyond that: partial-update semantics ('only fields you pass are changed'), null-clears-nullable-field behavior, the exact scope of the daily loop switch ('does not stop scheduled posts'), vacation-mode semantics, the Pro-only gate on caption_tag_hidden, and the side effect that notification_email becomes the sign-in email for Instagram-first accounts. These are precisely the traits annotations cannot express.

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

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

The field inventory is front-loaded and each clause carries information, with the critical safety rule about notification_email framed as a prohibition. It is a single dense paragraph that reads as a wall of text rather than being chunked, which costs a point, but there is little genuine filler to cut.

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

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

For a 10-parameter mutation tool with no output schema and only 50% schema coverage, the description supplies the missing semantics, the merge/patch contract, the null-clear rule, permission and ownership restrictions, and tier gating. An agent has everything needed to call it correctly without guessing.

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

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

Schema description coverage is only 50%, and the description compensates thoroughly, assigning meaning to nearly every undocumented field: notification_email, timezone, automation_enabled (the daily loop = daily drafts + approval email), schedule_paused, default_publish_time (HH:mm), whatsapp_notify_enabled/whatsapp_to_e164, and caption_tag_hidden. It adds semantics the bare schema lacks, especially for the boolean flags that carry no schema description at all.

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 noun phrase 'Tenant automation settings' plus the enumerated fields makes it unambiguous that this tool mutates tenant-level automation configuration (email recipient, timezone, daily loop, vacation mode, publish time, WhatsApp, caption tag). It is clearly distinguishable from adjacent siblings like edit_schedule, set_flow, and set_day_note, which govern per-item scheduling or notes rather than account-wide automation.

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

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

It gives strong conditional guidance: 'schedule_paused ... only when the owner asks', 'notification_email must be an address the user gave you — never one you guessed or looked up', and 'only fields you pass are changed'. That is real when-to-use and precondition information. It stops short of naming alternatives (e.g., when to prefer edit_schedule over changing default publish time), so it is 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?

Annotations declare destructiveHint=true and idempotentHint=true, and the description confirms replacement ('Replaces the previous note') and clearing behavior. It also adds important context about the 36-hour effect and the need to ask the owner rather than invent. It doesn't detail permissions or error conditions, but given the annotations, this is quite transparent.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose and then adds key behavioral details. It is concise and avoids redundancy, though it could be slightly more scannable with separate sentences for clearing and downstream effects.

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

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

Given the tool's complexity (affects story drafts, has destructive/idempotent behavior, requires context parameter), the description covers purpose, effect on downstream processes, replacement semantics, clearing mechanism, and a key constraint (ask owner). It lacks details on handle parameter usage and any error handling, but with 100% schema coverage and annotations, it is largely complete.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description repeats the note parameter's purpose and clearing behavior, and adds no additional semantics for context or handle parameters. Baseline 3 is appropriate.

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

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

The description clearly states a specific action ('Give Pith one line... about what is true today or tomorrow') with concrete examples and explains the effect on downstream story drafts. It distinguishes itself from siblings like generate_draft by focusing on setting a daily note, not creating content. However, it doesn't explicitly contrast with other configuration tools like set_automation or set_flow, which is a minor gap for a 4.

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

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

It provides clear context: use this to tell Pith what's happening today, and every story draft in the next 36 hours will be based on it. It implies when to use it (daily updates) and includes an instruction ('Ask the owner, never invent'). However, it doesn't explicitly state when NOT to use it or name alternative tools for similar purposes, which prevents 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 flag destructiveHint=true; the description supplies the specifics an agent actually needs: switching reseeds a starter config and clears TODAY'S pending drafts while preserving approved/published ones. That is exactly the beyond-annotation context this dimension rewards, and it is consistent with the destructive 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?

Front-loaded with the action and its destructive side effects before the dense field-by-field rules, so nothing is buried. The single long paragraph is information-dense but would scan faster with light structuring; still, every clause carries real instruction.

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

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

For a mutation tool with a nested config object and no output schema, it covers destruction semantics, per-flow field rules, and the ownership constraint on post_mix. It omits anything about error conditions or what the call returns, but with no output schema that omission is minor.

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

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

Schema covers ~75% of fields, and the description compensates heavily by mapping config fields to flows and giving constraints absent from the schema (≤10 reference images, ≤2000 brand prompt, end ≥ start, ≤60 assets that must exist, 1-3 posts/day). It leaves some fields like source_post_indices and show_prices unelaborated, so not a full 5.

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

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

Opens with a specific verb+resource: 'Switch the tenant's daily flow and/or patch its configuration.' It also separates the two modes (switch vs patch), which lets an agent distinguish it from the read-only sibling get_flow without opening either schema.

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

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

Gives explicit conditional guidance for the post_mix field ('Never set it on your own initiative: ask the user which they want') and states that omitting flow only patches config. It never names an alternative tool or a when-not-to-use-this condition, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to establish that it mutates. It goes further and specifies what is destroyed ('clears the previous crawl state') and the normalization behavior for bare domains, which annotations cannot convey. Only gaps are return shape and any auth/permission constraints.

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

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

Three tight sentences, front-loaded with the core action, then normalization, then side effects and the required follow-up. No filler and every sentence carries operational information.

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

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

For a destructive, no-output-schema mutation tool this covers the important ground: what it sets, what it clears, and what to call next. Lacking only the return value / confirmation behavior, which for a setter is a minor omission.

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

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

Schema coverage is 67%, and the one underspecified parameter (website, which only carries maxLength in the schema) is precisely the one the description explains: bare-domain normalization example and empty-string clearing semantics. Adds real meaning beyond the schema for the key input.

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 ('Set (or clear) the tenant's business website URL') and immediately distinguishes itself from the sibling refresh_website by naming the follow-up action. An agent can tell exactly what this tool does and how it differs from nearby tools.

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

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

Explicitly routes the agent: 'call refresh_website afterwards to read the site (Brand-DNA enrichment + product import + image review candidates)', and tells how to clear via website: "". Both the when-to-use and the follow-up dependency are stated rather than implied.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds real context: edit 'implies approval', unschedule clears a pending schedule, convert_to_reel is gated by plan, and published/rejected/failed drafts are immutable. It does not state permission requirements or what the call returns, so it stops 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?

One tight paragraph, front-loaded with the tool's role, then the action enumeration, then the terminal-state constraint. 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?

For an 8-parameter mutation tool with a nested object and no output schema, the description covers actions, conditional requirements, plan gating, and immutability, which is most of what an agent needs. It leaves the caller without any sense of the response or post-mutation state, which is the remaining gap.

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

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

Schema coverage is 75%, and the description adds cross-parameter semantics the schema cannot express: schedule_at only applies to approve, overlay_lines/overlay_spec are required for edit, and unschedule clears an existing schedule. This is meaningful value beyond the per-field descriptions, though a couple of parameters (handle, reason) get no extra framing.

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

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

The description names a specific verb and resource ('the approval-inbox verb') and then enumerates every accepted action value (approve, reject, edit, unschedule, convert_to_reel) with its own qualifier. An agent can tell this apart from publish_draft and edit_schedule 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?

Per-action preconditions are spelled out (approve optionally takes schedule_at, edit requires overlay_lines and/or overlay_spec, convert_to_reel is Pro-only) plus a state exclusion (terminal drafts cannot be changed). What is missing is explicit routing against siblings such as publish_draft or edit_schedule, so alternatives are implied rather than named.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations: it reveals that the tool exposes granted scopes and that it should be called first (ordering dependency). No contradictions 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?

Three sentences with no redundancy: the first front-loads the purpose and outputs, the second conveys the ordering usage, and the third gives the alternative route. Every sentence earns its place.

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

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

Given the tool's simplicity, full schema coverage, and safety annotations, the description is largely complete: it explains what data is returned, when to call it, and how to handle the no-account case. It lacks return-format details (no output schema), but nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the schema already provides a detailed, prescriptive description of the 'context' parameter (word count, third-person perspective, example). The tool description adds no parameter-specific meaning, so the baseline of 3 applies.

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

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

The description explicitly states the verb 'identify' with a specific resource ('the connected pith.day user') and enumerates the exact data fields returned (email, linked Instagram accounts with capabilities, plan tier, scopes). This distinguishes it from siblings like connect_instagram or get_billing_status.

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

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

The description gives explicit usage guidance: 'Call this first to discover the handle other tools need' and provides a clear conditional alternative: 'No accounts yet? Use connect_instagram to link one.' This tells the agent exactly when to use this tool and when to use a sibling.

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