Pith - Instagram Publishing

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

Beyond the write-implying annotations, the description discloses meaningful behavior: the URL is mirrored into storage and the original can expire, base64 is limited to 8MB decoded, and exactly one source must be supplied. 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 two dense sentences that front-load the core action and then cover source alternatives, constraints, and use cases. Every clause adds useful information with no filler.

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

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

For a five-parameter tool with no output schema, the description covers the key invocation choices and constraints agents need. The role of handle and caption is left to the schema, and the return value is not described, but neither is essential for a safe call.

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

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

The schema already covers handle, caption, context, and the two image fields, so the description does not need to repeat them. It adds value by defining the exactly-one constraint, the 8MB decoded limit, and the no-data-prefix base64 convention that are not enforced or fully specified in the schema.

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

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

The description clearly states the verb and resource: imports an image into the tenant's asset library. It also distinguishes the accepted source types and typical use cases, so an agent can tell this apart from list_assets, delete_asset, and curate_images.

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

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

It gives explicit when-to-use guidance for the two input modes: URL when a public URL exists, base64 when the agent holds the image. It also names representative use cases, but it does not explicitly exclude alternatives or mention sibling tools such as curate_images.

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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description discloses operational behaviors that materially affect invocation: the link expires in 10 minutes, works only once, requires a fresh call for a new link, and corrects handle typos to the authorized username. These details add real context and are consistent with the annotations, so there is 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?

Four dense sentences, each earning its place: purpose, browser workflow, expiry/single-use semantics, and the professional-account prerequisite. The most important information — what the tool does and why — is front-loaded in the first sentence with zero filler.

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

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

With no output schema, the description still conveys what the tool returns (a one-time link) and covers the full lifecycle: how to use the link, how to confirm success via whoami, when to re-call, and the account-type limitation. An agent has everything needed to invoke it and verify the outcome.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning for the handle parameter by stating that 'typos in the handle are corrected to the authorized username.' This relaxes the exact-match requirement implied by the schema and tells the agent precision on the handle is not failure-critical.

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

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

The first sentence states a specific verb and resource: 'Get a one-time link that connects an Instagram Business/Creator account to Pith so publish_post can post to it.' This both names the exact operation and ties it to its downstream consumer, and it is clearly distinguishable from all 30+ siblings, none of which handle account connection.

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

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

The description gives an explicit workflow ('Open the link in a browser, approve on Instagram, then call whoami to confirm'), a clear when-not ('personal accounts cannot use Instagram's publishing API'), and re-call guidance for expired links. It does not name an alternative tool for competing scenarios, but no sibling serves this function, so the routing to whoami and publish_post is sufficient context.

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 beyond the annotations by disclosing quota consumption ('COUNTS toward the Free monthly stories cap on the first call per draft'), the idempotent re-fetch behavior, and a concrete latency risk ('cold render can take 60-90 seconds'). This is valuable behavioral context the annotations 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?

Three tight sentences: front-loaded action and purpose, then quota implications, then latency. Every sentence adds distinct information, with no filler or repetition.

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

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

For a tool with no output schema, the description specifies the return value (a rendered story image URL), the cost implications, the re-fetch behavior, and an important performance caveat. This is sufficient for an agent to call the tool 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?

The schema already documents 'handle' and 'context' well, and the description adds meaningful context for 'draft_id' by mentioning draft lifecycle states ('already published/downloaded drafts are free to re-fetch'). The description does not restate parameter syntax, but the missing draft_id docstring is partially compensated by the tool's name and the behavioral notes.

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 ('Resolve the rendered story image URL') and states the intended workflow ('save-and-post-yourself'). This clearly distinguishes it from auto-publishing siblings like publish_draft and from generic draft retrieval tools like get_draft.

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

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

The phrase 'for save-and-post-yourself' gives clear context for when to use the tool: when the user wants to manually post a rendered story image rather than publish automatically. It does not explicitly name alternatives or exclusions, so it falls just short of perfect 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 only declare not read-only and not destructive. The description adds substantial behavioral context: remove is a soft-delete, scheduled dates resolve in the tenant's timezone at the default publish time, approval_mode=email is the only accepted mode with auto/warning refused while auto-publishing is off, and approved drafts require an explicit publish_draft call. This goes well 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?

Roughly 100 words, dense but efficient. The action dispatch is front-loaded and each clause earns its place; the approval_mode caveat, critical for correct invocation, is clearly stated. Slightly heavy for a tool definition, but 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?

For a 15-parameter, 4-mode mutation tool with no output schema, the description covers action semantics, hard constraints, soft-delete behavior, and publish routing. Gaps remain: it doesn't map which parameters are required per action (draft_id for update/remove lives only in the schema) and doesn't describe error cases, but the critical correctness constraints are all present.

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 40%, so the description carries meaning for the most consequential parameters: the action enum's four values and their effects, approval_mode's hard constraint, scheduled_date's timezone/default-time semantics, slides' 2-10 limit, and days meaning 'next N days'. A few params (beat_slug, source_asset_id, caption_mode vs user_caption) still lack semantic explanation beyond the schema, so it doesn't fully compensate.

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?

Title and description both use specific verbs plus a clear resource: 'Add / update / remove scheduled posts' and 'Manage scheduled posts'. The description enumerates four distinct action modes (add, update, remove, bulk_fill) with precise semantics for each, and distinguishes itself from the sibling publish_draft by stating that publishing is a separate explicit call.

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 (managing scheduled posts) and explicitly routes the publishing step away to the sibling tool publish_draft, noting the owner's app tap as the alternative. It does not cover sibling routing for reading schedules (get_schedule) or one-off AI generation (generate_draft), so exclusion guidance is only partial.

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?

The annotations already indicate destructive behavior, but the description adds substantial context: payment gate, monthly story cap, publish lease preventing double-posts against the cron, retry with backoff, and refusal of scheduled drafts. This goes well beyond the binary annotation signals and prepares the agent for failures and concurrency 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?

Two dense sentences with no filler. The key constraint appears early, and the pipeline details are compressed into one effective phrase. Every clause contributes decision-relevant information.

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

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

The description covers purpose, prerequisites, exclusions, concurrency protection, and retry behavior. It does not explain return values or what happens on payment/cap failure, and there is no output schema to fill that gap. Still, an agent has enough context to call the tool correctly and prepare inputs.

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 and context with good detail, leaving draft_id undocumented. The description indirectly clarifies draft_id by requiring an approved draft, but it does not directly explain the parameter. Overall the description adds only modest 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 names the action and resource: publish one approved draft to Instagram immediately. It is specific and accurate, but it never distinguishes itself from the sibling publish_post tool, so an agent must infer when each tool applies.

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

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

It gives explicit when-to-use guidance (approved drafts only) and a hard when-not (scheduled drafts are refused, unschedule first). It also directs users to update_draft first. It does not, however, mention alternatives like publish_post or otherwise contrast with similar 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?

The description goes well beyond the annotations: it reveals the monthly quota exemption, anti-abuse bound, Free plan watermark behavior, the finalCaption output the agent can rely on, story-caption ignoring, and safe timeout/idempotency semantics. These are meaningful behavioral details not implied by readOnlyHint, openWorldHint, or destructiveHint 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?

The description is dense but front-loaded with the core action and then layers plan/caption/timeout semantics. Every sentence contributes useful operating information, though some details slightly overlap with the schema, such as the idempotency guidance. It is longer than minimal but appropriate for a mutating tool with multiple modes.

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 (9 parameters, no output schema, multiple post types), the description covers all decision-critical behavior: connected-account prerequisite, immediate publication, plan-specific caption watermarks, story caption behavior, carousel slide counts, and safe retry semantics. An agent has what it needs to invoke this tool correctly and avoid duplicate posts.

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 practical semantics beyond the schema: the idempotency_key retry flow with draft_id, the fact that stories ignore captions, and that finalCaption reflects what was actually posted. These additions help the agent choose and sequence the parameters correctly.

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

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

The description names a specific verb and resource: publish the user's own images and caption to their connected Instagram account, and clearly differentiates the three content forms (story, feed, carousel). It also distinguishes itself from sibling tools by emphasizing bring-your-own-content and immediate publishing. This makes the purpose unmistakable even alongside publish_draft.

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

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

The description clearly states key usage conditions: it requires a connected account, publishes immediately, and does not support scheduling. It also positions this as the free, non-quota-consuming publishing surface organically, though it does not explicitly name publish_draft or other alternatives as the recommended alternative.

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

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

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 establish readOnly=false, destructiveHint=false, idempotentHint=true, so the description does not need to repeat safety traits. It adds meaningful behavioral detail beyond annotations: partial updates, null-clearing semantics, and a Pro-only gating caveat for caption_tag_hidden. No contradiction with annotations is present.

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: one front-loaded list of the settings and one concise sentence on update/null semantics. Every phrase carries information, and there is no filler. The long enumeration is a bit listy, but it remains readable and useful.

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 most operationally important information: scope, fields, partial updates, null clearing, and Pro gating. However, it omits the timezone value format, leaves the two WhatsApp-related parameters somewhat ambiguous under the single phrase 'WhatsApp approval pings', and does not indicate what the tool returns. These are not fatal because the schema fills some gaps, but they are noticeable for a 9-parameter tool with no 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?

With 56% schema description coverage, the description helpfully maps parameter meanings in prose: 'daily-email recipient' to notification_email, 'daily loop on/off switch' to automation_enabled, and 'default publish time (HH:mm)' to default_publish_time. It also clarifies the behavior of null for nullable fields, which adds value beyond the schema's anyOf declarations. The main gap is that it does not explicitly tie each prose item to its exact schema property 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 clearly identifies the resource as tenant automation settings and enumerates the specific fields it can change, which distinguishes it from sibling tools like edit_schedule and set_flow. However, the opening is a sentence fragment and relies on the title 'Update automation settings' to supply the verb, and it does not explicitly contrast with nearby tools.

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

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

The description gives useful invocation semantics—'Only fields you pass are changed; pass null to clear a nullable field'—but it does not state when to prefer this tool over alternatives such as edit_schedule or set_flow, nor does it mention any exclusions or prerequisites. The usage context is only implied by the word 'automation settings'.

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?

Even with destructiveHint=true, description adds precise destructive scope: clears TODAY'S pending drafts but preserves approved/published. It also discloses that switching reseeds a starter config, which agents need to know before calling.

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

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

Two dense sentences pack purpose and per-flow config rules without filler. Front-loaded with action and effect, then compact field mapping.

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?

Description gives purpose, side effects, and per-flow config constraints enough to call. It doesn't describe return value/errors, but no output schema exists and expected response for a mutation tool is less critical; could add a note on get_flow for reading current config.

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

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

Schema covers constraints, but description adds per-flow field mapping ('recycle → source_post_indices + slots_per_day'), date ordering, and asset existence requirement. It doesn't repeat handle/context since those are already well described in 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?

Description opens with specific verb 'Switch' and resource 'the tenant's daily flow and/or patch its configuration', then details the consequence (reseeds starter config, clears pending drafts). This clearly differentiates set_flow from read-only get_flow and other sibling tools.

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

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

It distinguishes two usage modes (switching flow vs patching config) and indicates flow omission preserves current flow. It lacks explicit 'use get_flow to read current' or exclusions relative to set_automation, but the per-flow mapping gives strong contextual 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?

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 already indicate mutation (readOnlyHint=false) and non-destructive, but the description adds substantive behavior: edit implies approval, unschedule clears a pending schedule, convert_to_reel requires Pro, and terminal statuses are immutable. This gives an agent the state-machine context it needs.

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 tool's role and then compress all action-specific behavior without filler. The description earns its length and is 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?

For a 7-parameter mutation tool with no output schema, the description covers actions, dependencies, plan restrictions, and immutable states. It could add expected result/response behavior and clarify whether approve publishes immediately when schedule_at is omitted, but it is otherwise complete enough to call correctly.

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

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

Schema coverage is 71%, and the description adds useful semantics beyond the schema: schedule_at uses HH:mm in the account timezone, edit requires overlay_lines and/or overlay_spec, and unschedule clears a pending schedule. Not every parameter is enriched, but the high-value ones are.

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 begins 'The approval-inbox verb' and enumerates the five supported actions (approve, reject, edit, unschedule, convert_to_reel) on a draft, so the resource and operation are specific. It does not explicitly name sibling tools, but the action list and title make 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?

The description implies its usage context (approval inbox for drafts) and gives a when-not rule: terminal drafts cannot be changed. It does not mention alternative tools or explain when to prefer a sibling like publish_draft or get_draft, so usage guidance is mostly implied.

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

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

Annotations already declare readOnlyHint=true and 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.