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 provide idempotentHint=true and destructiveHint=false, so the description doesn't need to repeat those. It adds value by clarifying that action determines the outcome (apply vs dismiss) and that this is a decision point. It does not describe side effects like whether the proposal is removed after dismissal, but the annotations cover safety. 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?

Two sentences, front-loaded with purpose and action definitions. The second sentence adds the critical context about owner's explicit choice without any fluff. 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?

For a mutation tool with no output schema, the description lacks information about the result of applying or dismissing (e.g., confirmation, updated DNA, whether the proposal is cleared). It also doesn't mention prerequisites like the proposal must exist or that the owner's identity is required. Referencing get_brand_dna helps, but an agent may need more detail on the effects and any return value.

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%, with drift_id and action lacking descriptions. The description compensates by explaining the action enum values and implying drift_id is obtained from get_brand_dna. It doesn't add anything for handle or context, but those have detailed schema descriptions. This is a reasonable compensation given the partial 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 states a clear verb ('Resolve') and resource ('pending Brand DNA drift proposal'), and explicitly defines the two outcomes (apply adopts, dismiss rejects). It differentiates from siblings like refine_brand_dna or regenerate_brand_dna by focusing on the final decision step, and references get_brand_dna for the pending proposal, making the purpose unambiguous.

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

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

It tells the agent to look up the pending proposal via get_brand_dna, and that only the owner's explicit choice should drive this. However, it does not explicitly state when NOT to use this tool (e.g., if refinement is needed) or compare it to refine/regenerate alternatives, so there's some room for improvement.

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?

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?

The description adds useful behavioral detail beyond annotations: idempotence per day, the SLOW LLM-call cost, and force/slot semantics. However, it directly contradicts the destructiveHint:false annotation by saying force=true wipes today's PENDING drafts first; wiping is destructive. Per rubric, the contradiction forces a score of 1.

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 short and front-loaded with the purpose, and each following sentence covers a distinct operational concern (idempotence, force, slot targeting, cost). The hyphenated guard phrases are somewhat jargon-heavy but do not bloat the 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 5-parameter generation tool with no output schema, the description covers core behavior, idempotence, and cost, but it never states what the tool returns or how the active flow is determined. No output schema means the description should at least describe the result shape, so the definition is not fully complete.

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

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

Schema coverage is 80% and the description adds meaning where it matters: force has no schema description but the description defines its destructive re-run behavior, and slot_index is tied to asset flows and `_s{n}` draft ids. It doesn't describe context, but the schema already does, so the added value 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 action and scope: it runs the daily draft engine to generate today's pending drafts for the active flow. This distinguishes it from sibling tools like regenerate_draft and list_drafts, whose names imply different operations.

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

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

It gives clear context: run for the day's pending drafts, re-running fills gaps, force is for wiping pending drafts first, and slot_index lets a single failed slot be re-fired. It does not explicitly name alternatives or exclusions, but the intended triggers are inferable from the operational description.

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=true and destructiveHint=false, and the description's 'List' verb is consistent. The description adds meaningful behavioral context by specifying UTC instants, tenant timezone inclusion, and rejection filtering—details beyond the structured annotations.

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

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

Two sentences with zero waste. The core action and filtering are front-loaded, and the second sentence adds necessary time-format info. 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 no output schema, the description covers what is returned (drafts with scheduled times) and key output characteristics (UTC, timezone display). It does not mention pagination or return field structure, but for a simple read-only list tool this is a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific meaning beyond the schema; it only indirectly references output behavior (timezone) rather than explaining the handle or context 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 uses a specific verb ('List') with a clear resource ('every draft with a scheduled publish time'), includes ordering ('soonest first') and an exclusion ('excluding rejected ones'). This clearly differentiates it from siblings like list_drafts (all drafts) and edit_schedule (a mutation).

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 defines the exact scope of the tool ('drafts with scheduled publish time') and the exclusion criterion, giving an agent clear context on when to use it. It does not explicitly name alternatives or state when not to use it, but the sibling names and scope imply the distinction from list_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 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?

Despite annotations already flagging readOnlyHint=false and destructiveHint=false, the description adds substantial behavioral context: archive is a soft delete that also drops the product from the flow pool, set_description with empty string clears, price -1 clears, and owner-set prices are display-grade and may appear on rendered stories (FLOW-14). These disclosures materially change how an agent predicts outcomes and are not redundant with the annotations.

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

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

The description is dense but every sentence contributes: the opening defines scope, the action enumeration packs parameter requirements into a compact list, and the final sentence adds a crucial behavioral caveat. No filler or repetition; the structure front-loads the purpose and then drills into action specifics.

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 tool with 9 parameters, 7 actions, and no output schema, the description covers all action-specific semantics and edge cases (clearing, deletion behavior, display-grade pricing). The main gap is that it does not describe return values (e.g., what create returns) or error conditions, but this is partially mitigated by the detailed parameter guidance and the absence of an output schema. An agent can confidently call the tool correctly, though a note on response shape would round it out.

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 22%, so the description carries the load. It explains the meaning and constraints of most parameters in context: name is required for create, product_id is needed for rename/archive/set_description/set_price, price is in major units with an example (82 for ₪82), currency defaults to ILS, and asset_id must come from list_assets. This goes well beyond the bare schema and enables correct invocation.

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 clear verb-resource pairing ('Product CRUD') and then enumerates each action with required parameters, leaving no ambiguity about what the tool does. It is easily distinguished from siblings like list_products (read-only) and add_asset/delete_asset (asset lifecycle) because it scopes to product records and their photo attachments.

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 clarifies when to use this tool: any mutation to products or their photos in the daily-products flow. It also supplies action-specific usage details (e.g., add_photo needs asset_id from list_assets; create requires name; price -1 clears). It does not explicitly say 'use list_products for read-only queries' or name alternative tools, but the context is sufficiently implied and the cross-reference to list_assets nudges the agent toward the correct pairing.

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?

Discloses key behaviors beyond annotations: the operation is slow (60-120s with scrape+OCR+DNA+classify), idempotent on success, uses a 24h scrape cache, and refuses already-owned handles. This reinforces and expands on the idempotentHint=true annotation without contradicting readOnlyHint=false or destructiveHint=false.

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

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

The description is dense but every sentence earns its place: purpose, uniqueness, timeout behavior, idempotency, and next steps. It is front-loaded with the core action and ends with practical follow-up routing, with minimal fluff.

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

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

For a complex mutation-like tool with no output schema, it covers creation semantics, exclusivity, failure/timeout behavior, and next steps well. The only notable gap is that it never states the structure or contents of the return value, but the idempotency and follow-up guidance partially compensate for 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?

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds context around idempotency and post-conditions but does not add parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

Purpose is explicit: 'Create and link a NEW pith.day account from a public Instagram handle', with concrete steps (scrape, derive Brand DNA, classify flow, seed drafts). It distinguishes itself from siblings by stating it is 'the ONLY tool that links a tenant to your user (MCP-17)'.

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

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

Provides clear when-to-use guidance: only this tool links a tenant to the user, handles already owned by another account are refused, and it is safe to call again on timeout. It also names follow-up tools (get_tenant, curate_images, get_flow/set_flow), which is actionable routing advice.

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 (which only flag destructive/openWorld). It discloses quota behavior, the Free-plan '✨ Posted with pith.day' caption watermark and how finalCaption reveals the exact posted text, that stories ignore captions, and the timeout/idempotency contract with draft_id resumption that prevents double-posting.

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

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

It is long, but dense and front-loaded: the core action and modes come first, then constraints, then the idempotency contract. Nearly every sentence carries non-obvious operational information, though a few clauses (e.g. the anti-abuse bound) could be trimmed.

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 mutation tool with no output schema and destructive/openWorld annotations, the description covers prerequisites, side effects, plan-dependent behavior, immediate-publish semantics, and safe-retry mechanics. An agent has everything needed to call it correctly.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real operational meaning on top: how idempotency_key is reused on retry, and that draft_id resumes a prior call without double-posting. Remaining parameters (handle, slides, caption) get no extra guidance 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 (publish), resource (the user's own image + caption), destination (connected Instagram account), and enumerates the supported modes (story, feed, 2-10 image carousel). It is clearly distinguishable from the sibling publish_draft, which handles generated drafts rather than bring-your-own content.

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 scopes usage: this is the free/own-content surface, requires a connected account via connect_instagram, and scheduling is explicitly not supported (posts go out immediately). It also names the alternative path implicitly by contrasting own-content posts with the draft flow.

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 only sparse annotations, the description carries the transparency burden and does so well: it discloses that the LLM produces a schema-validated patch, that preview_only=true returns the patched DNA without saving, and that otherwise the change is persisted immediately. This clarifies the mutation side effect beyond what readOnlyHint=false and destructiveHint=false convey.

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

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

The description is two tight sentences that front-load the tool's purpose and examples, then add the key preview/persist behavior. There is no redundant restatement of the title or schema details, and 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?

Together with the detailed schema descriptions for handle and context, the description gives an agent enough to invoke the tool correctly: what to put in message, what preview_only does, and that a non-preview call persists immediately. It could be more explicit about the return shape for the persisted path, but that is a minor gap given the absence of an output schema.

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

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

The schema already documents handle, context, and message, but leaves preview_only without a description; the tool description fills that gap by explaining preview_only=true returns without saving and otherwise persists. It also enriches message semantics with plain-language examples. This goes beyond the schema's baseline 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 identifies a specific action (natural-language edits to Brand DNA) and resource (Brand DNA), backed by concrete examples like 'warmer voice' and 'switch palette to sage green'. It also frames the tool as a patch generator, which distinguishes it from siblings like get_brand_dna and regenerate_brand_dna, though it does not name those tools explicitly.

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 direct usage guidance: describe a change in plain language, and use preview_only=true to avoid persisting. This makes the basic invocation clear. However, it never states when to prefer get_brand_dna or regenerate_brand_dna instead, so alternatives and exclusions are missing.

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 declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive write operation. The description adds crucial context: it is slow (60s+), it replaces the current DNA, and it requires user confirmation. It does not contradict annotations, and the added behavior (slow, confirmation) goes beyond the annotation hints.

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

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

The description is concise and front-loaded with the most critical information (re-scraping and re-deriving), followed by the warning about slowness and replacement. Every sentence earns its place, and the alternative tool is mentioned efficiently.

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 (slow, destructive, requires confirmation) and the absence of output schema, the description covers all necessary aspects: purpose, when to use, side effects, and user confirmation. The agent has enough to decide and invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description does not add further detail about the parameters beyond the schema, which is acceptable at this coverage level. No extra parameter-specific guidance is given, but it's not necessary.

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 (re-scrape Instagram and re-derive Brand DNA), the resource (Brand DNA), and the scope (from scratch). It distinguishes itself from the sibling refine_brand_dna by explicitly noting it does a full re-derivation rather than adjustments.

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 tells the agent when to use this tool (when a full re-derivation is needed) and when not to (prefer refine_brand_dna for adjustments). It also warns about the slowness and the need for user confirmation, providing clear context for decision-making.

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 discloses non-obvious side effects: resetting the draft to pending, invalidating the cached render, and tier-specific daily rate caps. These details go well beyond the sparse annotations and help the agent predict what invoking the tool will change.

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

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

One dense, front-loaded sentence states the action, the optional steering, and the important side effects. The follow-up sentence adds rate limits with no 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?

The description covers the essential behavioral context an agent needs before calling the tool, and the schema handles the strict context/prompt requirements. It does not describe return values, but there is no output schema and the return format is not necessary for correct invocation.

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

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

The description adds meaning beyond the schema by clarifying that draft_id refers to one draft's story text and that angle steers the re-draft. It does not mention handle or context, but the schema already documents those in detail, including the strict context word-count requirements.

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

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

States a precise operation: re-drafting one draft's story text with an optional angle. This clearly distinguishes it from generate_draft by indicating an existing draft, and also mentions follow-up effects like resetting to pending and invalidating the cached render.

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 behavior implies when to use it, but it never explicitly says 'use this instead of generate_draft for an existing draft' or names alternatives/exclusions. Rate caps give some usage context, but there is no explicit routing among sibling tools.

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

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

Annotations already state idempotentHint=true and destructiveHint=false, so the description's 'only fields you pass are changed' aligns and adds partial-update semantics. It also flags a Pro-only field and a critical email-provenance rule, which are genuine beyond-annotation details. It does not, however, describe response behavior or any permission requirement beyond Pro.

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 definition is compact and front-loaded, listing affected settings first, then the update semantics, then the email constraint. It is not bloated, but the final clause about Instagram-first accounts is a dense edge case packed into the same 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 9-parameter mutation tool with no output schema, the description covers the important caveats (partial update, null clearing, Pro gating, email provenance), but it omits what the tool returns and leaves four parameters entirely undocumented. It is adequate but not 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 56%, so several parameters (timezone, automation_enabled, whatsapp_notify_enabled, notification_email) are undocumented in both schema and description. The description adds semantics for null-clearing, default_publish_time format, and Pro gating, but it leaves the remaining parameters unexplained, so it only partially compensates for the coverage gap.

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

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

The description enumerates exactly which settings are mutated (daily-email recipient, timezone, automation on/off, default publish time, WhatsApp pings, caption tag), giving an agent a clear picture of the resource and the fields affected. It is specific, though it does not explicitly distinguish itself from adjacent utilities like edit_schedule or set_flow.

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

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

There is no explicit when-to-use or when-not-to-use guidance, no prerequisites, and no comparison to siblings such as edit_schedule. The behavioral rule about notification_email being user-provided is a constraint rather than usage routing.

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

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

Annotations declare destructiveHint=true, but the description details the destructive effect: clears TODAY'S pending drafts while preserving approved/published drafts. It also explains flow-switch reseeding and config persistence for post_mix. This adds behavioral context beyond the annotations.

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

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

The description is dense but appropriately structured, front-loading the core effect (switching clears drafts) then grouping per-flow configs. Every sentence adds value, though a slight restructuring into bullets could improve scannability. Still, it's not verbose given the tool's complexity.

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 all parameter meanings, flow-specific constraints, and behavioral side effects. It lacks explicit error-handling or return-value details, but since there is no output schema and the tool is configuration-focused, the description is sufficient for an agent 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?

The description enriches every parameter: it maps config fields to flows (e.g., recycle → source_post_indices + slots_per_day), explains post_mix values and the rule to ask the user, and details feed_days behavior under 'both'. Schema coverage is 75%, but the description compensates fully for the remaining 25% and clarifies semantics.

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

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

The description clearly states the tool switches the tenant's daily flow and/or patches its configuration. It enumerates specific flow types and config fields, distinguishing it from get_flow and other sibling tools. The verb 'switch' and resource 'flow' are explicit.

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

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

Provides explicit when-to-use guidance: switching flows reseeds starter config and clears pending drafts, while config patching is per-flow. It warns against setting post_mix on the agent's own initiative and explains feed_days conditions. This is beyond basic usage and routes the agent appropriately.

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?

Given the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds valuable behavioral context: it mentions that setting a new URL clears previous crawl state, which is a side effect not captured by the annotations. This is beyond what annotations provide. The description does not contradict annotations. A 4 is appropriate because it provides useful side-effect disclosure but could have been more explicit about potential side effects of clearing.

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 concise (3 sentences) and front-loads the core action (set or clear) and the primary detail (bare domains accepted). It includes relevant examples and follow-up instructions without extraneous fluff. Every sentence adds 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 simple setter tool with only 3 parameters and no output schema, the description provides all necessary context: what the tool does, how to use it, the side effect of clearing crawl state, and the need for refresh_website. The context parameter is about meta-analysis and is well documented in the schema. 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?

The schema description coverage is 67%, meaning two parameters (handle and context) have descriptions, but website does not. The description adds semantics for the website parameter: it mentions bare domains and the clearing behavior, which is helpful. However, since the schema covers most parameters, the baseline is 3, and the description adds moderate 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 clearly states the tool's purpose: to set or clear the tenant's business website URL. It gives a specific verb and resource, and distinguishes it from refresh_website by explaining that setting a new URL clears crawl state and that refresh_website is needed afterwards. This differentiates it from the sibling 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?

The description explicitly explains when to use this tool (to set/clear the website) and provides a follow-up action: 'call refresh_website afterwards'. It also clarifies the clearing behavior with 'Pass website: "" to clear'. No exclusions are needed because the purpose 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 only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the description carries real weight and delivers: edit implicitly approves, unschedule clears a pending schedule, convert_to_reel requires a Pro plan, and terminal drafts are immutable. These are meaningful behavioral constraints beyond the annotations, though return behavior is unstated.

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

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

Very economical — one dense paragraph with each parenthetical earning its place, and the action list is front-loaded. The heavy use of compressed parentheticals makes it slightly harder to scan than a clean numbered list would, but there is no wasted 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 an 8-parameter dispatcher tool with nested objects and no output schema, the description covers the action semantics and mutation constraints an agent needs to call it correctly. The one gap is what happens on success (e.g. whether edit re-renders the draft), but annotations and schema otherwise fill the space.

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 genuine semantics on top: schedule_at is 'HH:mm' in the account timezone, reason is reject-only, and edit requires overlay_lines and/or overlay_spec. It explains the action enum's side effects rather than just listing values, going beyond what the schema states.

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

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

The description opens with 'The approval-inbox verb' and then enumerates all five actions (approve, reject, edit, unschedule, convert_to_reel) with their individual effects. This clearly separates it from siblings like publish_draft, get_draft, and regenerate_draft, which handle different points in the draft lifecycle.

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

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

It states action-specific requirements (edit needs overlay_lines and/or overlay_spec, reject takes a reason, schedule_at only applies with approve) and gives an explicit when-not: 'Terminal drafts (published/rejected/failed) cannot be changed.' It does not, however, route to sibling tools such as regenerate_draft or publish_draft.

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.