PostNitro

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

Annotations already declare readOnly and idempotent behavior. The description adds meaningful behavioral nuance beyond the annotations, such as the GENERATE_IMAGES log status values and the fact that the overall post can still be COMPLETED even if image generation fails. 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 concise and well-structured, using two focused sentences. It provides necessary context without any redundant or irrelevant 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 conveys the expected outcome (status and processing logs) and highlights an important edge case about image generation failures. While it does not detail the exact output schema, that information is indicated as externally available, so the description is sufficiently complete for usage.

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

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

There is only one parameter, embedPostId, and its schema description ('The embed post ID to check') fully covers its meaning. The tool description adds no additional semantic detail about the parameter, so the score stays at the baseline for full 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 identifies the tool's purpose: checking generation status and processing logs for a post. It includes useful specific detail about the GENERATE_IMAGES step, which distinguishes it from general post retrieval tools, though it does not explicitly name sibling 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?

The description gives implicit guidance about what to expect, especially the best-effort nature of image generation and the possibility of COMPLETED overall status despite an image failure. However, it does not explicitly state when to use this tool versus related siblings like get_scheduled_post or get_output.

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 (readOnly=false, destructive=false, idempotent=false), the description adds two real behavioral facts: the plan-level cap on brand count and that exceeding it returns an error. It also confirms the new brand's ID is returned. It does not mention the idempotencyKey retry-safety mechanism, though the annotations' idempotentHint=false is not contradicted since the safety comes only from the explicit key.

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

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

Three short paragraphs: purpose first, then the required-fields/returned-ID mechanic, then the error caveat. Every sentence carries information an agent would otherwise have to infer, and nothing is repeated from the schema verbatim.

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

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

With an output schema present, return values need not be spelled out, yet the description still notes the returned ID and its intended use. It covers required-field enforcement and a failure mode (plan cap). The only gap is any mention that retries should reuse idempotencyKey, which is left entirely to the schema for a non-idempotent create.

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 every parameter including the richly documented idempotencyKey already carries its own semantics. The description only adds the aggregate constraint 'all seven fields are required' and the framing that the fields are stamped onto carousels, which is a marginal gain over the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

The lead sentence gives a specific verb+resource ('Create a new brand kit') and immediately defines what a brand kit is ('the logo, name, and handle stamped onto generated carousels'), which the bare name 'Create Brand' does not convey. Against siblings like postnitro_update_brand, postnitro_get_brand and postnitro_list_brands the create semantics are 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 tells the agent what to do with the result — 'use it as a brandId in generate/import or save it via postnitro_set_defaults' — which gives clear downstream context with no exclusions. It does not explicitly say 'if a brand already exists, use postnitro_update_brand instead', so the create-vs-update decision is left implicit.

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

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

Annotations only say it's a non-read-only, open-world, non-destructive write with no idempotency guarantee; the description goes well beyond that by disclosing the API-enforced validation rules (future scheduledAt, designId required for SCHEDULED on LinkedIn/Facebook/Pinterest, conditional *PostSettings per platform), the error-message surfacing behavior, and the reel-audio fallback semantics. This is exactly the mutation-risk context an agent needs before spending credits or scheduling a live post.

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

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

Purpose is front-loaded in one sentence, followed by a scannable numbered workflow and a compact rules block. There is minor redundancy with the schema (the embedPostId warning and reel-audio rule appear in both), but no sentence is wasted.

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

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

For a 13-parameter tool with deep nested objects, the description supplies the workflow, cross-platform conditional requirements, and validation rules, and the output schema covers return values. It leaves a small gap around when to choose this versus the generate/import-and-schedule wrappers, which an agent could otherwise resolve from the description.

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 every parameter is already documented in structured fields, and much of the description's parameter content (embedPostId vs designId, postSettings audio fallback) restates the schema. It adds only light cross-field framing — that selected accounts' platforms drive which *PostSettings become required — so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a scheduled post or draft') and enumerates the exact platforms covered, including the Page/board nuance for Facebook and Pinterest. An agent can immediately tell this is the scheduling-creation tool rather than an edit, generate, or import 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 numbered workflow gives concrete preconditions (call postnitro_list_social_accounts first, optionally obtain a designId from postnitro_get_output / postnitro_generate_and_wait) and states the 'at least one of designId or postContent' rule. It stops short of routing against close siblings such as postnitro_generate_and_schedule, postnitro_import_and_schedule, or postnitro_update_scheduled_post, so the agent must infer when this tool is the right entry point.

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 (destructiveHint=true, idempotentHint=true) by explaining irreversibility, the requirement to confirm with the user, the refusal behavior for audio in scheduled posts, and the fact that rendered MP4s keep their audio. 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?

Two concise paragraphs: the first states the action and irreversibility; the second covers two important edge cases. No redundant words, and the critical information is front-loaded.

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

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

The description covers all key operational aspects: irreversibility, confirmation need, dependency on scheduled posts, and behavior with rendered videos. With an output schema present and the simplicity of one parameter, nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100% — the audioId parameter has a clear description ('The audio ID to delete (get from postnitro_list_audio)'). The tool description adds no extra parameter semantics, but the schema already handles it, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Permanently delete an audio file from the workspace, including the stored file.' It specifies the verb (delete), resource (audio file), and scope (workspace and stored file), distinguishing it from sibling tools like postnitro_delete_scheduled_post.

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

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

It gives practical guidance: confirm with the user first due to irreversibility, and warns that audio referenced by scheduled posts is refused, requiring removal from those posts first. It doesn't explicitly name alternatives, but none exist for this operation; the context is clear enough.

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?

Explicitly warns that the action cannot be undone, reinforcing the destructiveHint annotation. Also mentions deletion of related content, providing side-effect detail.

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, concise and front-loaded with the primary action.

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

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

Adequate for a simple delete operation; no extra context needed.

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

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

The single parameter scheduledPostId is well-described in the schema with a source reference. The tool description does not add extra meaning but is consistent.

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?

Clearly states the action (delete) and the target (scheduled post or draft) and scope (related content). Distinguishes from other scheduled post tools by its destructive nature.

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?

Does not explicitly compare to alternatives like update_scheduled_post, but the destructive intent is clear. Lacks guidance on when to use vs other tools, so a moderate score.

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 that the action cannot be undone and that it removes the account from every scheduled post, which are essential side effects. This aligns well with the destructiveHint annotation and provides sufficient transparency for the user.

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, using only two sentences with no redundancy. It covers the action, the key consequence, and the irreversible nature without unnecessary detail.

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 delete operation, the description covers the primary effects (account removal and scheduled post removal) and irreversibility. It doesn't address edge cases like non-existent account IDs, but that is not essential for typical use. Overall, the description is complete enough for an agent to understand the tool's purpose and impact.

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

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

The single parameter 'socialAccountId' has its meaning and source fully described in the schema itself ('get from postnitro_list_social_accounts'). The description adds no additional semantic value beyond the schema, 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 clearly states the verb 'disconnect' and the resource 'social account', and explicitly notes that it deletes the account and removes it from scheduled posts, making it unambiguous. It is distinct from list/get operations for social accounts.

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?

While it doesn't explicitly name alternatives, the description implicitly guides usage by emphasizing the irreversible nature and the impact on scheduled posts, which are critical warnings for when to use this operation. The sibling tools for listing/retrieving accounts are obvious non-destructive alternatives.

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

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

Beyond the annotations, it discloses the full-replacement semantics (which is important given destructiveHint=false), that the edit propagates to scheduled posts, the 1-credit-per-slide cost, and the async result flow via postnitro_check_status then postnitro_get_output. This is rich behavioral context the structured fields do not carry.

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

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

Purpose and routing are front-loaded, but the body is one dense run-on chain with cryptic clauses like 'its slides replaced as import takes them.' Every clause carries information, yet the compression and length make it harder to parse than necessary.

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

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

With annotations, an output schema, and full schema descriptions present, the description fills the remaining gaps: replacement semantics, cost, API-post restriction, async flow, and the waiting sibling. 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 coverage is 100%, so the schema already documents all ten parameters. The description adds only high-level keep-vs-replace logic for templateId/brandId and videoSettings, largely mirroring what the schema states verbatim, so it does not meaningfully exceed the schema baseline.

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

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

States a specific verb and resource (edit a post made through the API) and immediately scopes it: it replaces ALL slides in place while preserving designId, name, template look/size, brand and video style. The final sentence names the sibling it is not (postnitro_edit_post_and_wait), so an agent can route correctly without opening the schema.

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

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

Explicitly says to read first with postnitro_get_post and send back every slide to keep, restricts usage to API-created posts, and names the alternative postnitro_edit_post_and_wait. Both the precondition and the sibling alternative are stated, not inferred.

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

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

Discloses what is destroyed and what is preserved: ALL slides are replaced in place, while designId, name, template look/size and video style/audio survive unless the corresponding override is given. It also notes the downstream effect on scheduled posts and the cost model ('1 credit per slide sent'), which annotations alone do not convey.

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

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

Front-loaded with the core action and the key replacement semantics in the very first sentence, but the second sentence is a long chained clause covering five separate retention rules, which is dense to parse even though nothing in it is filler.

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

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

Covers workflow, cost, retention semantics and API-only eligibility for a 10-parameter nested tool with an output schema. Gaps are small: nothing about polling timeout/failure behavior or about the idempotencyKey retry contract that the schema defines.

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

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

With 100% schema coverage the baseline is 3, and the description earns above it by explaining the keep-vs-replace semantics of templateId/brandId/videoSettings and the 'send every slide you want kept' contract for the slides array, which the schema itself does not frame as a replace-all operation.

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

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

States a specific verb and resource ('Edit a post made through the API') plus the synchronous behavior ('poll until it completes, and return the output'), which distinguishes it from postnitro_edit_post and postnitro_get_post without opening either schema.

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

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

Gives an explicit prerequisite workflow ('Read it first with postnitro_get_post and send back every slide you want kept') and a hard eligibility rule ('Only posts made through the API can be edited'), so the agent knows both how to prepare and when the call will fail.

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

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

Goes well beyond the annotations: discloses 30-180s latency (longer for video), that the operation burns credits and regeneration is costly, that designId is auto-resolved from result.designId rather than the job ID, and that failures return the designId for cheap retry. The annotations only state openWorld/non-idempotent/non-destructive, so this added context carries real weight. 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?

Front-loaded with the core behavior, then organically layered into short paragraphs covering defaults, designId resolution, failure recovery, and field expectations. Dense but every sentence adds actionable information for a 22-parameter composite tool.

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

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

Given a complex 22-param composite with nested settings and an output schema, the description covers the critical agent decisions: latency expectations, credit cost, ID resolution, retry-without-regenerating path, and default fallbacks. Nothing essential 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 coverage is already 95%, so baseline is 3. The description still adds value: it clarifies when templateId/brandId/presetId can be omitted (saved defaults), explains designId's auto-resolution and when to set it manually, summarizes postType options, and tells the agent to supply scheduling fields exactly as for postnitro_create_scheduled_post.

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

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

States a specific composite verb chain (generate with AI → wait → create scheduled post) and the resource (design/carousel/scheduled post). It names the sibling it complements (postnitro_create_scheduled_post) and disambiguates itself from the standalone generate_* and create_scheduled_post tools by calling itself a 'convenience tool'.

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

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

Gives clear context for when this one-shot path is appropriate and an explicit fallback: if scheduling fails after generation, retry with postnitro_create_scheduled_post using the returned designId to avoid burning credits. It also points to postnitro_set_defaults for optional IDs. It does not state when an agent should prefer the split generate-then-schedule flow for finer control, so it stops short of a full when-not/alternatives statement.

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

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

Adds behavior beyond the annotations: it discloses the polling loop and a 30-180 second runtime, which is the single most important trait for an agent deciding whether to block on it. It does not mention credit consumption or the paid-plan requirement for image generation (those appear only in the schema's generateImages text), and it doesn't reconcile with idempotentHint=false.

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

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

Two short paragraphs, front-loaded with the action and its cost in time, then the routing alternative and the defaults caveat. No sentence is filler.

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

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

For a wait-style generation call with an output schema and rich parameter docs, the description covers latency, alternatives, and defaults fallback. The remaining gap is the relationship to postnitro_generate_carousel / postnitro_check_status (the manual path) and the credit cost of generation.

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

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

Schema coverage is 88%, so the schema already carries nearly all parameter meaning, including the defaults-related optionality. The description's note that templateId/brandId/presetId/responseType can be omitted after set_defaults largely restates what those property descriptions already say. Baseline 3 for a high-coverage schema.

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

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

States a specific verb and resource ('generates a carousel with AI, polls until completion, and returns the final output'), plus the 'convenience' framing that distinguishes it from the lower-level generate/get pair. It also explicitly names the single-image sibling, so an agent can route without opening schemas.

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

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

Gives a clear use condition (want a finished carousel in one call) and points to postnitro_generate_image_and_wait for single images, plus the latency expectation that tells the agent what it is committing to. It never contrasts with the non-waiting sibling postnitro_generate_carousel, which is the main alternative an agent would weigh.

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

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

Annotations only cover the safety profile (not read-only, not destructive, not idempotent), so the description's key addition is the async job model: the call returns an embedPostId and work continues in the background, which is real behavioral information. It does not mention credit consumption or added latency for the base call (the schema covers those only for image generation), so it falls short of full disclosure.

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

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

Four short paragraphs, front-loaded with purpose and return value, then alternatives, IDs, and workflow. Every block is functional, with only mild redundancy between the defaults sentence and the schema's identical wording.

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

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

For an 8-parameter async generator with nested objects, the description supplies the job lifecycle, alternatives, and dependency resolution, and an output schema exists so return values need not be restated. Credit/cost implications and failure modes are left entirely to the schema, which is the main residual 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 88%, so the schema already explains every parameter including the defaults fallback. The description largely restates it ('templateId, brandId, presetId, and responseType are optional if you've saved defaults'), adding only the pointer to use list tools for valid IDs. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('generate a carousel post using PostNitro's AI engine') and immediately discloses the async contract ('Returns an embedPostId to track progress'). It explicitly names the sibling it is not for ('For a single-image post instead of a carousel, use postnitro_generate_image'), so an agent can distinguish it 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?

Covers the alternative path (generate_image for single images, generate_and_wait for one-step), the prerequisite for IDs (set_defaults or list tools), and the downstream sequence (check_status then get_output). When-to-use guidance for the main alternatives is all present in one place.

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

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

Annotations already establish that this is not read-only or destructive and is closed-world. The description adds useful behavioral context: it is an asynchronous generation job returning an embedPostId, does not accept slides, and may rely on saved defaults. It does not repeat schema-level credit/quota details, but the annotations and schema carry that burden.

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

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

The description is front-loaded and compact, with three short paragraphs that each add distinct information: what it generates, how it relates to alternatives, and how to track the job. No sentence is wasted.

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

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

For an 8-parameter asynchronous generation tool with nested objects, the description covers the essential decision points: AI-generated content, optional saved defaults, tracking flow, and the one-step alternative. An output schema exists, so return-value details need not be explained in the description.

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 high at 88%, so the schema already documents most parameters. The description adds value by clarifying that templateId, brandId, presetId, and responseType can be omitted when saved defaults exist, and by pointing to list tools for valid IDs.

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: generating a single-image post (postType IMAGE) using PostNitro's AI engine. It distinguishes itself from postnitro_import_image and from postnitro_generate_image_and_wait, so an agent can choose correctly 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?

It explicitly routes the agent: use this tool when content should be AI-generated from aiGeneration, and use postnitro_import_image when supplying custom image content. It also explains the defaults behavior and both monitoring paths via postnitro_check_status/postnitro_get_output or postnitro_generate_image_and_wait.

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

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

Annotations only say it is a non-read-only, non-destructive, non-idempotent write, but the description adds real behavior: it polls until completion, takes 30-180 seconds, and images are best-effort so the post still completes if they fail or the plan does not permit them. It also warns that image generation requires a paid plan, consumes a separate quota, and adds latency, and points at postnitro_check_status for the GENERATE_IMAGES step.

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

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

Front-loaded with the core action and latency, followed by the content-source rule and the defaults note. It is compact, but the defaults sentence partly repeats what the schema already says for each optional parameter.

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

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

Covers the long-running nature, the content-source choice, plan and quota constraints, best-effort image behavior, and the retry/no-wait alternatives; an output schema exists, so return values need not be explained. The only gap is that it does not explain the difference from postnitro_generate_and_wait or when to use the non-waiting variant instead.

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

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

Schema description coverage is already 88%, so the baseline is 3. The description adds meaning beyond the schema by stating that aiGeneration drives the content and that you do not provide slides, and by grouping templateId, brandId, presetId, and responseType as default-fillable. The image-generation caveats are documented in the schema, not repeated here, which is appropriate.

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

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

States a specific verb and resource (AI-generates a single-image post, postType IMAGE), plus the polling behavior and that it returns final output. This distinguishes it from the non-waiting postnitro_generate_image and from postnitro_import_image_and_wait, which it names 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?

Gives explicit routing: use this when content should be AI-generated from an aiGeneration prompt, and use postnitro_import_image_and_wait to supply your own image content. It also flags which params can be omitted via saved defaults. It does not distinguish this from the sibling postnitro_generate_and_wait or state when not to wait at all.

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 readOnly/destructive/openWorld/idempotent flags, so the description carries the real burden and does it well: it discloses that motion is applied without asking, that runtime is capped at 2:00, what DESIGN vs MP4 means, and the async tracking flow. It stops short of describing cost/credit implications of credit-charging beyond the image note, so not a 5.

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

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

Front-loaded with the core action and the embedPostId return, then organized under short labeled sections (Output, Motion). It runs a bit long and the final sentence partly restates the async workflow, but nearly every line carries actionable information.

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

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

With an output schema present, the description needn't detail return values — yet it still names embedPostId and points to check_status/get_output for retrieval. Combined with the motion, defaults, and content-sourcing guidance, an agent has everything needed to invoke this 9-parameter, nested-object tool correctly.

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

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

Schema coverage is already 89%, so baseline would be 3. The description adds value by explaining the defaults fallback for templateId/brandId/presetId/responseType and by directing the agent to the list tools for valid IDs, which is semantic guidance the schema does not repeat.

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

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

States a specific verb and resource ("Generate a video post (postType VIDEO)") plus the engine used, and explicitly distinguishes itself from postnitro_import_video (user-supplied scenes) and postnitro_generate_video_and_wait (one-step variant). An agent can pick this over its siblings without opening a schema.

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

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

Gives explicit routing: use postnitro_import_video to supply your own scene content, call postnitro_list_motion_styles/sequences to find saved IDs, rely on postnitro_set_defaults for optional IDs, then poll with check_status/get_output or use the _and_wait sibling. Both when-to-use and when-not are covered.

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

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

Adds substantial context beyond the annotations: 15-45s render times that stretch with animations/GIFs, the 2:00 MP4 failure mode (design is kept, not lost), and that motion is applied without asking. The idempotencyKey description also explains the retry contract, which usefully qualifies the idempotentHint=false annotation rather than contradicting it.

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

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

Front-loaded with purpose, the alternative, and the cost/latency caveat before details; every paragraph addresses a real decision. Slight redundancy with the schema (the motionStyle/sequenceId explanation is restated in both places) keeps it from a 5.

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

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

For a long-running, 9-parameter, nested-object tool it covers what an agent actually needs before calling: that no slides are supplied, expected duration, the output-format tradeoff, the duration limit and its failure behavior, and that IDs can come from defaults. An output schema exists, so it rightly does not describe return values.

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

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

Schema coverage is already 89%, so the baseline is 3, but the description adds decision-level meaning: responseType determines whether a file is rendered at all, motionStyle accepts built-in names or saved style IDs, and sequenceId overlays a saved sequence on every slide. It does not walk through every nested field, but it covers the ones that change behavior.

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

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

Opens with a specific verb+resource+lifecycle: 'AI-generates a video post (postType VIDEO), polls until completion, and returns the final output.' It is clearly distinguishable from postnitro_generate_video (no polling) and from postnitro_import_video_and_wait, which it names directly.

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

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

Explicit routing: 'The content is AI-generated from your aiGeneration prompt — you do NOT provide slides. (To supply your own scene content instead, use postnitro_import_video_and_wait.)' Plus guidance on when to pick DESIGN vs MP4 and when optional IDs can be omitted via saved defaults.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, which cover the safety profile. The description's 'Fetch' action aligns with these annotations and adds no contradictory or extra behavioral context, so a baseline score is appropriate.

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 that starts with the main verb 'Fetch'. It efficiently lists the display settings without unnecessary detail, making it easy to parse.

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 single-resource fetch, the description is complete: it states what is fetched (brand kit with display settings) and how to identify it (by ID). No additional context is needed for this tool's scope.

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 for brandId is present, giving 100% coverage. The description adds a helpful cross-reference to postnitro_list_brands for obtaining the ID, which is extra value beyond the schema, so a score above baseline is warranted.

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 (Fetch), the resource (brand kit), and the scope (by ID). It distinguishes from list_brands (fetch all) and update_brand (modify) by specifying a single brand and listing the display settings included.

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 usage when you have a specific brandId, and the parameter description cross-references postnitro_list_brands for obtaining the ID. However, it does not explicitly contrast with alternatives or provide explicit when-to-use guidance beyond the ID requirement.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the null-return behavior when no defaults are saved, which is not covered by annotations. This extra detail helps the agent anticipate outcomes.

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

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

Single sentence, front-loaded with the action and key return fields, with no redundant wording. Efficient and to the point.

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 parameterless getter with safety annotations and an output schema, the description fully covers the essential information: what it retrieves, the return null case, and no side effects. Nothing missing for correct invocation.

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

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

The tool has zero parameters, so the description correctly omits parameter details. The baseline for 0-parameter tools is 4, and the description adds no unnecessary parameter info.

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 clearly states the verb 'retrieve' and the specific resource (saved default templateId, brandId, presetId, responseType) and its return behavior (null if none). This distinguishes it from sibling tools like postnitro_set_defaults and other getters.

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: retrieve saved defaults. It does not explicitly mention alternatives or when-not-to-use, but given the sibling set_defaults, the context is clear. No exclusions are stated, but the purpose is unambiguous.

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

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

Annotations already declare readOnlyHint and idempotentHint true and destructiveHint false, covering the safety profile. The description adds that it returns a template and notes one slide per scene, but does not discuss side effects, auth, rate limits, or output shape beyond that.

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

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

The description is concise, front-loaded with the core return value, and uses the em dash to add relevant format context without unnecessary 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?

Given the tool has no parameters and likely has an output schema, the description provides enough context to know what to expect and when to call it. It names affected sibling tools and clarifies the shared slide-array format.

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

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

The tool accepts no parameters, so the baseline of 4 applies. The description adds format context but no parameter semantics are needed.

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 clearly states the tool returns the exact slide structure and rules for the import tools, and names the specific sibling import tools it supports. This makes its purpose distinct from other get/list tools.

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

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

Explicitly instructs to call before using postnitro_import_carousel, postnitro_import_and_wait, or video import tools, and clarifies that video posts share the same slide array format. This gives direct when-to-use guidance and resolves format 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 readOnly/idempotent/non-destructive, so the safety story is covered. The description adds genuine behavioral context beyond that: output varies by post type (single URL for PDF/MP4, per-page URLs for PNG, fields omitted entirely for DESIGN output). It omits failure behavior when the post isn't finished yet.

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

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

The first sentence front-loads the core purpose, then the return-shape detail follows in a logical order. It is dense with parenthetical detail but each clause (designId handoff, editorUrl, per-type file behavior) carries information the agent needs.

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

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

With an output schema, annotations, and a single documented param, the description is nearly complete — it covers the workflow handoff (designId) and the conditional return shape. The only gap is what happens when the post is incomplete or the ID is invalid.

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

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

Only one parameter, embedPostId, and the schema already documents it at 100% coverage. The description adds no further meaning about the ID (e.g., where it comes from), so it neither compensates nor detracts — the baseline 3 applies.

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

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

States a specific verb and resource: 'Retrieve the generated output for a completed post.' It also names the artifacts returned (designId, editorUrl, rendered files), which lets an agent distinguish it from get_post/get_scheduled_post. It doesn't explicitly contrast with those siblings, so it falls short of a 5.

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

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

The 'completed post' precondition implies you must wait for generation before calling, and it names the downstream tools (postnitro_create_scheduled_post / postnitro_generate_and_schedule) that consume the returned designId. It never explicitly tells the agent to use a different tool when the post is not yet complete, so no exclusions are present.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond that: the exact response shape (import-tool design format, slides vs. a single slide object for IMAGE), inclusion of brand data, and that the call is free.

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

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

A single dense sentence with the identifier and return shape front-loaded; nothing is wasted. The phrasing is slightly compressed ('its design in the shape the import tools take'), but it still reads cleanly.

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

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

With an output schema present, the description needn't enumerate return fields, and it still previews the design shape and brand inclusion. For a one-parameter read tool this is essentially complete, with only the sibling distinction left implicit.

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

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

Schema coverage is 100% and the schema already states the parameter is an embedPostId 'not a designId'. The description's mention of embedPostId largely repeats that, adding no format or syntax detail. Baseline 3 is appropriate when the schema does the work.

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

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

Names a specific verb (Read) and resource (a post made through the API) plus the key identifier (embedPostId), and characterizes the returned design shape ('slides, or one slide object for an IMAGE'). This is far more specific than the title, though it never names the sibling it is distinct from (e.g. postnitro_get_scheduled_post, postnitro_get_output).

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

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

'Use it to see what a post says before editing it' supplies a concrete triggering context and even a cost note ('Free'), which is actionable. It stops short of explicit exclusions or naming an alternative when a caller wants a scheduled post versus an API post.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds what content the response contains, but no additional behavioral context such as error behavior for unknown IDs or any access restrictions. With annotations carrying the safety burden, this is adequate but not rich.

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

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

A single front-loaded sentence that names the action, the lookup key, and the payload contents with no filler. Every clause earns its place.

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

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

With rich annotations, a fully documented parameter, and an output schema covering return values, the description needs only to state the resource and scope, which it does. Minor gap: no note about behavior when the ID does not exist or refers to a deleted post.

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

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

Only one parameter exists and schema description coverage is 100%, with the schema itself explaining the ID and its source. The description adds nothing beyond 'by ID', so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a single scheduled post by ID') and enumerates the returned facets (captions, social accounts, platform settings, design details, publishing status). An agent can distinguish it from postnitro_list_scheduled_posts, postnitro_update_scheduled_post, and postnitro_get_brand without opening any schema.

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

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

Usage is only implied: it is clearly the single-item counterpart to postnitro_list_scheduled_posts, and the schema's parameter description tells the agent where to obtain the ID ('get from postnitro_list_scheduled_posts'). There is no explicit statement of when to prefer this over the list tool or what happens on an invalid/missing ID.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds what the payload contains (post usage by status, token expiry), which is useful context but is also reflected in the output schema; it says nothing about auth requirements, rate limits, or what happens on a stale/invalid ID.

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 sentence, front-loaded with the action and resource, with the payload detail trailing. No filler or repetition, and nothing an agent needs is buried.

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

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

For a single-parameter read tool with an output schema present, the description need not explain return values and is largely complete. The only gap is the absence of any routing statement toward the list sibling, which matters given 34 siblings.

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% for the single parameter, so the schema already explains socialAccountId and where to obtain it. The description only restates 'by ID' and adds no format/syntax detail beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a single connected social account by ID') and even previews the payload (status-broken-down usage, token expiry). The word 'single' implicitly contrasts with the plural list sibling, but no sibling is named explicitly, so an agent must infer the split from postnitro_list_social_accounts.

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 when-to-use or when-not-to-use guidance appears in the description; the only routing hint ('get from postnitro_list_social_accounts') lives in the schema, not the description. It never states the alternative for enumerating accounts, leaving the agent to infer that this is the ID-known lookup path.

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 non-readonly, openWorld and non-idempotent, so the safety bar is covered; the description adds real operational context they don't: a 15-60 second runtime, and the partial-success behavior where a scheduling failure still returns the created designId so the agent can retry without re-importing. It does not mention the idempotencyKey retry contract, which is left entirely to the schema.

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

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

Front-loaded with the convenience framing and latency, with capped IMPORTANT markers for the prerequisite and failure-recovery notes. Slightly sprawling — the scheduling-fields paragraph and the failure/retry paragraph both reference postnitro_create_scheduled_post and could be merged.

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 22-parameter composite tool with deep nesting and an output schema, the description covers the full flow, the mode selection, the template prerequisite, defaults fallback, and the partial-failure recovery path. Per-platform settings are correctly delegated to postnitro_create_scheduled_post semantics, and return values are covered by the output schema, so nothing an agent needs 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, and the description mostly restates the postType branching and the slides-vs-slide distinction that the schema already spells out. It adds some genuine value by explaining that designId is resolved automatically from result.designId unless overridden, and by deferring slide shape to postnitro_get_import_template.

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 composite verb chain (import own content → wait → create scheduled post attaching the result) and explicitly labels itself a convenience wrapper, which distinguishes it from postnitro_import_carousel/postnitro_import_and_wait and postnitro_create_scheduled_post. It even names the three import siblings it mirrors by postType.

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

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

It gives a hard prerequisite ('Call postnitro_get_import_template FIRST'), explains when defaults make templateId/brandId/responseType optional, and routes to postnitro_create_scheduled_post for retry after a partial failure. It does not explicitly say when to pick this over the plain import tools (e.g. if you don't want a scheduled post), leaving one selection decision implicit.

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

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

Annotations already declare the non-read-only, non-destructive profile, and the description adds the blocking/polling nature, the 15-60s wait, and a concrete list of structural validation rules that will cause failure. It does not disclose credit consumption or what happens on timeout — the idempotency behavior lives only in the schema.

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

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

Front-loads the one-line purpose and latency, then prerequisites, then numbered rules — a logical order for an agent to act on. Minor redundancy: several 'strict rules' restate the schema's own enum/description text, costing a few lines without new information.

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

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

With an output schema present, return values need no explanation, and the description covers prerequisite ordering, defaults substitution, latency, and structural constraints. What remains thin is the relationship to the non-waiting sibling and what to do if the wait times out (the idempotency guidance is stranded in the schema).

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds enforcement-level meaning absent from the field docs: slide ordering/count constraints, the columnCount<=3 ceiling, the cycle-first-column rule, and the infographic-replaces-image interaction. These are partly mirrored in the nested schema but framed here as hard rules an agent must satisfy before calling.

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

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

States a specific verb+resource (imports custom slide content) plus the blocking behavior (polls until completion and returns the final output), which cleanly separates it from the async 'import_carousel' and the AI-driven 'generate_carousel' siblings. The 15-60 second latency note further pins down what kind of call this is.

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

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

Gives an explicit prerequisite sequence ("Call postnitro_get_import_template FIRST") and clarifies that templateId/brandId/responseType can be omitted when defaults are saved. It stops short of naming when to prefer this over postnitro_import_carousel or postnitro_import_and_schedule, leaving that routing to be inferred from the 'and_wait' suffix.

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

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

Annotations already declare it is not read-only, not destructive, not idempotent; the description adds real value beyond that by disclosing that strict structural rules are enforced and that violations cause errors. It does not mention credit consumption or how the tool relates to the scheduling variants, leaving some behavioral context to the schema.

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

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

Well front-loaded: purpose, then the prerequisite call, then numbered rules, then a compact example. A couple of the numbered rules (columnCount ≤ 3, columnDisplay cycle) restate what the schema descriptions already say, which is minor duplication in an otherwise tight definition.

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 deeply nested 7-parameter tool with an output schema and full schema coverage, the description supplies the two things structured fields can't: the mandatory template-discovery step and a concrete valid slide array. An agent can construct a correct call from this plus the schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond by adding ordering semantics for the slide array (exactly one starting_slide, at least one body_slide, exactly one ending_slide) and the columnDisplay "cycle" data-placement rule, plus a worked example. It still leaves the top-level optional params (requestorId, idempotencyKey) entirely to the schema.

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

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

States a specific verb and resource ("Create a carousel by importing your own slide content"), and the word "importing" implicitly separates it from postnitro_generate_carousel. However, it never clarifies how it differs from postnitro_import_and_schedule or postnitro_import_and_wait, which are the closest siblings by name.

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?

Strong operational guidance: an explicit prerequisite ("Call postnitro_get_import_template FIRST") and the note that templateId/brandId/responseType are optional when defaults are saved. What's missing is any statement of when to choose this tool over import_and_schedule/import_and_wait.

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 usefully supplements the annotations: it discloses that templateId/brandId/responseType fall back to saved defaults, that generateImages is best-effort and can still complete on failure, and that it requires a paid plan and consumes quota. However, it never explains the async model directly (it only implies it via 'embedPostId to track progress'), leaving the agent to infer that this returns a job rather than a finished post. Given the annotations already cover the mutation/idempotency safety profile, a 3 is appropriate.

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

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

Front-loaded with the core action, then object shape, then defaults, then the follow-up workflow. Every sentence maps to a real decision the agent must make and none is wasted repetition of the name.

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 nested infographic config and an existing output schema, the description covers the remaining gaps an agent would trip on: array-vs-object input shape, defaults handling, best-effort image generation, and the async retrieval path. Return values needn't be spelled out because the output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by clarifying the shape contract that the schema alone makes ambiguous ('single object, NOT an array, with no slide type') and by noting that an infographic layout, though nested in the slide, is a supported variant with the same config shape as carousel infographics. It stops short of explaining per-field meanings already in the schema.

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

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

States a specific verb and resource ('Create a single-image post (postType IMAGE)') and immediately distinguishes itself from the carousel sibling ('Unlike a carousel, an image post is ONE slide — pass slide as a single object, NOT an array'). An agent can select this over postnitro_import_carousel without opening either schema.

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

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

Explicit routing: use postnitro_check_status to monitor then postnitro_get_output to retrieve, or use postnitro_import_image_and_wait for a one-step flow. It also names the alternative (carousel) and the condition that separates the two (single slide vs array), leaving nothing to inference.

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

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

The description adds behavior beyond the annotations: it may take 15–60 seconds, polls until completion, and returns final output. It also notes that templateId, brandId, and responseType can be omitted when defaults are saved, which is useful operational context. Remaining gaps like credit use are covered partly by schema fields and output schema.

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

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

The description is front-loaded with purpose and latency, then moves to slide-shape constraints and defaults. Every sentence carries useful information, and there is no filler.

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

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

For a nested 7-parameter tool with an output schema, the description covers the important usage constraints: single-image scope, waiting behavior, slide shape, infographic support, and defaults. It is not fully complete because it omits explicit routing against several similar import/generate siblings.

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 the nested slide, layoutConfig, defaults, and responseType semantics. The description reinforces that `slide` must be a single object and that infographic layouts are supported, but most of this repeats the schema; the cross-reference to carousel infographic shape is the main additional value.

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

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

The first sentence names a specific verb and resource: it creates a single-image post from one slide, polls, and returns final output. That clearly distinguishes it from carousel/video tools, but it does not explicitly contrast itself with close siblings such as postnitro_import_image or postnitro_import_and_wait.

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

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

Usage is implied by 'Convenience tool' and 'polls until completion', so an agent can infer this is for cases where a final rendered result is needed. However, there is no explicit guidance on when to choose this over postnitro_import_image, postnitro_import_and_wait, or postnitro_generate_image_and_wait.

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

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

Beyond the annotations, it discloses the embedPostId return, automatic animation with a 2:00 cap, the DESIGN-vs-MP4 cost/latency tradeoff, voiceover token consumption and best-effort fallback, and paid-plan image requirements. That is substantial context the structured fields do not carry.

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

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

Front-loaded with purpose and the return value, then organized by Output/Motion/Defaults/Next-steps. It is dense but each section carries information; the repeated "the video is animated without asking" line is slight 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?

With 8 params, nested videoSettings/generateImages, an output schema and full annotation coverage, the description covers the remaining gaps: the slide/scene constraint, motion timing, and images being best-effort and quota-gated. Nothing essential to 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 coverage is 100%, so the schema already documents every parameter and baseline is 3. The description adds real meaning on top: the scene/slide structure rule, that motionStyle accepts built-in or saved styles discoverable via list_motion_styles/list_motion_sequences, and the timing behavior of the video.

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

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

The first sentence gives a specific verb and resource ("Create a video post ... from your own scene content") and implicitly distinguishes it from the AI-authored generate_video sibling. An agent can identify what it does and how it differs from a one-shot generation 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?

It routes the agent explicitly: use postnitro_check_status + postnitro_get_output to monitor, or postnitro_import_video_and_wait for one step, and explains the optional defaults via postnitro_set_defaults. It does not spell out when to prefer generate_video over import_video, leaving the AI-vs-own-content distinction to inference.

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

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

Goes well beyond the annotations: render latency (15-45s, longer with animations/GIFs), the 2:00 MP4 failure mode with design retained, best-effort semantics for voiceover tokens and image generation, and the note that images can fail while the post still completes. That is exactly the operational context the readOnly/destructive hints cannot convey.

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

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

Front-loaded with the core action and timing, then output mode, then motion, then defaults. Dense but nearly every sentence carries decision-relevant information; the motion paragraph is slightly compressed into telegraphic phrasing that costs readability.

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 long-polling creation tool with nested objects, an output schema, and eight parameters, the description covers timing, failure limits, token/quota costs, defaults fallback, and what 'DESIGN' returns versus 'MP4'. An agent can call this correctly without further context.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by framing responseType as a cost/latency trade-off, explaining that motionStyle accepts a built-in name or a saved style id, and stating that scene slides reuse the carousel array shape. It does not re-explain the nested videoSettings or generateImages fields, which the schema already covers well.

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

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

Opens with a specific verb and resource: 'creates a video post (postType VIDEO) from your own scenes, polls until completion, and returns the final output.' The phrase 'from your own scenes' plus the synchronous polling makes it distinguishable from postnitro_import_video and postnitro_generate_video_and_wait.

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

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

Gives clear decision criteria for responseType ('DESIGN' for scheduling/editor finishing, 'MP4' to render) and notes templateId/brandId/responseType fall back to postnitro_set_defaults. It stops short of explicitly naming alternatives ('use postnitro_generate_video_and_wait if you want AI-written content' or 'postnitro_import_video if you don't want polling'), leaving that inference to the 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 annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds transparency by detailing exactly what the response contains, and it does not contradict 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 concise, using two clear sentences. It front-loads the main purpose and immediately follows with useful return details and a relevant next-step hint.

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

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

With an output schema present, the description does not need to explain the return format. It provides enough context about the tool's role in the workflow, especially the relationship to setting defaults, making it 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 coverage is 100% and both parameters (page, limit) are described in the schema. The description does not add additional parameter context, so it remains at 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 states the tool's purpose: to list available AI configuration presets. It also names the specific resource (AI presets) and the fields returned, distinguishing it from other list tools like postnitro_list_templates and postnitro_list_brands.

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 the primary use case — browsing available presets before saving a preferred preset — by explicitly directing the user to postnitro_set_defaults afterward. It does not explicitly contrast with sibling tools, but the purpose is clear enough for an agent to choose this tool when listing presets.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: ordering, the fact that audio cannot be uploaded through this API (only listed and deleted), and the meaning of an empty result with a fallback action. That is exactly the sort of behavior an agent cannot infer from structured fields.

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

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

Front-loaded with the action and ordering, then routing guidance, then edge cases — a sensible order with little waste. The parenthetical about 'audioId, the older name' is slightly dense and could slow an agent parsing the field names.

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

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

An output schema exists, so return values need no explanation, and the description still covers the two behavioral edge cases an agent must handle: no audio in the workspace and multiple plausible matches. Nothing needed to call this correctly is missing.

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

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

Schema description coverage is 100% and both parameters (page, limit) are documented with defaults and bounds, so the schema carries the load. The description adds nothing about pagination behavior, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the audio files in your workspace') plus an explicit ordering ('newest first'). It is immediately distinguishable from postnitro_delete_audio and the other list_* siblings.

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

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

Gives an explicit trigger (resolve the ID for videoSettings.backgroundMusicId / postSettings.backgroundMusicId) and a hard constraint ('those fields take an ID, never a URL'). It also covers the empty-list path and the ambiguous-match path, telling the agent to present candidates rather than guess.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that it returns brand IDs, names, handles, and display settings, but this is likely already in the output schema. No additional behavioral traits (e.g., ordering, filtering, rate limits) are disclosed, so the description adds only marginal value beyond 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 concise with two sentences. The first sentence front-loads the purpose and return fields, and the second sentence provides a useful pointer to a related tool (postnitro_set_defaults). It is efficient and without fluff, though the second sentence is not strictly necessary for calling the tool correctly.

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

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

Given the tool's simplicity (2 optional parameters, no required params, output schema present, and annotations covering read-only/idempotent/non-destructive behavior), the description is complete. It states the tool's purpose, the return fields, and a relevant next step. 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?

Both parameters (page and limit) have complete descriptions in the input schema (100% coverage), including defaults and maximums. The tool description adds no extra semantics about how these parameters affect the results beyond what the schema already states. This matches the baseline of 3 when schema does the heavy lifting.

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

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

The description clearly states a specific verb ('List') and a specific resource ('available brand configurations'), and specifies the returned fields (brand IDs, names, handles, display settings). This distinguishes it from singular retrieval tools like postnitro_get_brand and creation tools like postnitro_create_brand without needing to inspect the schema.

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

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

The description does not explicitly compare this tool to alternatives or state when not to use it. It only implies usage for listing available brands, and the mention of postnitro_set_defaults suggests a follow-up action but not a selection criterion. The usage context is implied by the tool's nature as a list operation, but no explicit exclusions or alternatives are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts: results are scoped to a workspace and an empty list explicitly means nothing is saved (not an error), which prevents misreading of the response.

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-loaded with the resource and scope, followed by the actionable follow-up and the empty-state meaning. No filler and nothing left dangling.

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

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

With no parameters, full annotation coverage and an output schema handling return values, the description covers everything an agent needs to select and call it correctly, including scope and empty-result semantics.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. The only param-like reference ("videoSettings.sequenceId") belongs to other tools rather than this one, so it adds context without misdescribing this 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?

Uses a specific verb+resource ("List the workspace's saved motion sequences") and even defines what a motion sequence is ("one slide's animations, saved in the editor's Your sequences"). It does not explicitly contrast itself with the sibling postnitro_list_motion_styles, which is the most likely confusion point, so it stops short of a 5.

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

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

The description tells the agent what to do with a returned id ("Pass an id as videoSettings.sequenceId to put it on every slide") and how to read the empty case, which is useful downstream guidance. However, it never states when to call this versus postnitro_list_motion_styles, so the when-to-use decision is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety burden is off the description. The description still adds value by disclosing the result composition (14 built-ins plus workspace saved styles) and the ordering, which annotations cannot express.

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

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

Two short sentences, front-loaded with the primary statement of what is listed, followed by the practical consumption note. No filler or repeated information from annotations.

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

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

An output schema exists, so return values need no explanation here. The description covers scope, ordering and how to use the results; the only missing piece is differentiation from the sibling motion-sequences 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?

The tool takes zero parameters, so the baseline is 4. The description does go slightly beyond the empty schema by explaining that returned ids are consumed via videoSettings.motionStyle, which connects this tool's output to another tool's input.

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

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

States a specific verb and resource ('List the motion styles a video can take') and specifies the composition of the result: 14 built-ins followed by workspace-saved styles. It does not, however, distinguish itself from the sibling postnitro_list_motion_sequences, which an agent could easily confuse with this 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 closing sentence 'Pass an id as videoSettings.motionStyle' tells the agent how to consume a returned id, which is genuine downstream guidance. It gives no when-to-use guidance relative to alternatives such as postnitro_list_motion_sequences or postnitro_list_ai_presets, so the selection logic is left implicit.

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 read-only, idempotent, and non-destructive behavior. The description adds important edge-case behavior: filtering applies to posts, not to accounts within posts, and unknown socialAccountIds match nothing rather than causing errors.

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

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

The description is concise but complete. It avoids unnecessary detail while covering key behaviors and an example use case, with no redundant or confusing phrasing.

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 output schema is present and the description covers purpose, filtering behavior, edge cases, and examples, the tool description is fully sufficient for an agent to call it correctly.

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

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

All parameters are fully described in the schema, and the description adds practical details: ISO date recommendations, the 'at least one' account matching rule, the option to omit for all posts, and behavior for unknown IDs.

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: listing scheduled posts and drafts within a date range, with optional account filtering. It distinguishes itself from single-post retrieval by focusing on a date-ranged list operation.

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 usage context, including a practical example ('what's scheduled on my LinkedIn next week') and explains filtering semantics. It does not explicitly mention alternative tools, but the guidance is strong enough for correct 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 establish read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely useful non-inferable context: all six platform arrays are always present even when empty, Facebook entries are Pages and Pinterest entries are boards (each board its own account). It stops short of describing auth/scope requirements or whether pagination applies.

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

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

Front-loads purpose in the first clause, then the ID-contract in the second sentence, then edge-case notes. Three sentences, no filler. The parenthetical platform enumeration and the Facebook/Pinterest clarifications are dense but each carries information an agent needs.

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

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

An output schema exists, so return-value structure need not be restated; the description correctly focuses on the non-obvious contract (IDs fed into selectedAccounts) and the empty-array invariant. Combined with annotations covering safety, an agent has everything needed to call and consume the result.

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

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

Zero parameters, so the baseline is 4. The description instead invests in return-shape semantics (selectedAccounts ID contract, accountType values 'page' and 'board'), which is relevant for a no-param list tool even though a detailed output schema exists.

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

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

States a specific verb+resource ('List the connected social accounts in your workspace') and adds a meaningful grouping dimension ('grouped by platform') with the exact platform keys enumerated. Clearly distinguishable from siblings like postnitro_get_social_account (singular, by ID) and postnitro_list_brands (different resource).

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

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

Explicitly states the downstream use: 'These account IDs are what you pass as selectedAccounts when creating a scheduled post,' which routes the agent to postnitro_create_scheduled_post. It does not, however, contrast with postnitro_get_social_account or postnitro_disconnect_social_account, so an agent must still infer which list-vs-single tool to pick.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds value by specifying the output fields, which is not in annotations, and does not contradict any annotation.

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?

Description is two sentences, direct, and free of fluff or redundant details. Every word contributes to understanding the tool's function.

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 list operation, the description provides sufficient context: what is listed, what is returned, and a relevant pointer to a companion tool. It is complete given the output schema exists and no nested objects require explanation.

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 descriptions already cover both parameters (page and limit) with defaults and ranges (100% coverage). The description adds no additional parameter semantics beyond what the schema provides, so it remains at 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?

Description clearly states the verb 'List', the resource 'carousel templates', and explicitly mentions the return fields (IDs, names, dimensions). It is unambiguous and distinguishes from sibling list tools by resource type.

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

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

Provides a follow-up action (use postnitro_set_defaults) but does not explicitly state when to use this tool versus alternatives or when not to use it. The guidance is minimal and inferential.

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 context by stating that defaults persist and that MP4 cannot be saved as a default, which clarifies limits on future tool calls. The destructive and idempotent hints are already declared in annotations, and the description does not contradict them.

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

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

The description is concise and well-structured, with a short explanatory paragraph followed by a clear numbered workflow. No redundant or fluff content is present.

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 high schema coverage and explicit annotations, the description provides enough context for correct use. It explains persistence, how defaults are consumed, and important exceptions, though it does not describe the exact return value; this is acceptable since an output schema is 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?

Input schema coverage is 100% with detailed descriptions for each parameter, including special notes on responseType behavior. The tool description reinforces that all parameters are optional and sourced from list tools, adding practical guidance beyond the schema.

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

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

Clearly states that the tool saves default templateId, brandId, presetId, and responseType, and explains that these defaults are then used automatically by generate/import tools. This distinguishes it from sibling tools like postnitro_get_defaults and the individual generation 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?

Provides a practical first-time setup workflow and explains that defaults persist across sessions, so users know when to call this tool before running generate/import operations. It could be slightly stronger by explicitly contrasting with postnitro_get_defaults, but the usage context is clear.

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

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

The description discloses important behavioral details beyond annotations: name, handle, and image are only overwritten with non-empty values, while boolean display flags are always applied. This informs the agent of side effects and required care when updating.

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, front-loaded with the main purpose, and each sentence adds value. The tip is short and actionable, with no unnecessary 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?

The description is largely complete for an update operation, including behavior and a practical tip. It falls short slightly because of the incorrect field count, which could mislead an agent into omitting a required parameter. Otherwise, it adequately explains the update semantics and prerequisites.

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 all parameters with descriptions, so baseline is 3. The description adds valuable semantic context about conditional overwriting of name/handle/image and unconditional application of booleans. However, the statement 'All seven fields are required' is inaccurate—there are eight required parameters—which slightly undermines clarity about required fields.

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 updates an existing brand kit, distinguishing it from create or list operations. The verb 'update' and the resource 'brand kit' are specific and 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 provides explicit usage guidance by advising to call postnitro_get_brand first to read current values and send them back. This directly tells the agent when and how to use the tool correctly, especially given the conditional overwrite behavior.

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