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?

Discloses required fields, the plan cap failure condition, and that an ID is returned; complements annotations by specifying error behavior and output.

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 sentences plus a note; no fluff, purpose is front-loaded, and all key information is presented efficiently.

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

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

Covers purpose, output usage, and an error condition. Although no explicit output schema is shown, the description of the returned ID is sufficient for basic 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?

Schema description coverage is 100% and each parameter is described. The tool description restates that all fields are required but does not add deeper semantics 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 it creates a new brand kit (logo, name, handle) and distinguishes from sibling tools like update_brand, list_brands, and get_brand.

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 guidance on using the returned brand ID for generate/import or setting defaults, and mentions the plan cap error; does not explicitly contrast with update_brand but context makes it 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 thoroughly discloses behavioral requirements and edge cases: scheduledAt must be in the future, a post must have either a designId or non-empty postContent, platform-specific settings are conditionally required, and postSettings fallback behavior is explained. It also warns about the embedPostId pitfall. This goes well beyond the annotations, which only indicate low-level flags.

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 fairly long, but the content is well-organized into 'Workflow' and 'Rules enforced by the API' sections. Each sentence provides necessary information for correct usage. Some redundancy with schema descriptions exists, but it is purposeful for emphasis. The structure makes complex conditional logic approachable.

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 comprehensive for the tool's complexity. It references dependent tools (postnitro_list_social_accounts, postnitro_list_audio, postnitro_get_output), explains the designId vs embedPostId pitfall, details platform-specific settings requirements, and covers fallback behavior. An agent has all necessary context to correctly invoke the tool without needing to infer hidden rules.

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

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

The schema description coverage is 100% and each parameter already has detailed descriptions. The tool description adds value by reinforcing the designId vs embedPostId distinction, explaining the postSettings fallback, and outlining the conditional requirements across platforms (e.g., LinkedIn document rule). It does not introduce new parameter semantics beyond what the schema already provides, but it contextualizes them effectively.

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: 'Create a scheduled post or draft for LinkedIn, Instagram, TikTok, and/or Threads.' The verb 'Create' is specific, and the resource (a scheduled post/draft) is unambiguous. It also names the target platforms, so an agent knows exactly what to expect.

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

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

The description provides a step-by-step workflow (list social accounts, attach a design, provide caption, set post settings) and clarifies key rules (e.g., designId vs embedPostId, required platform-specific settings, postSettings fallback). It does not explicitly compare against sibling tools like postnitro_generate_and_schedule or postnitro_update_scheduled_post, but the workflow and conditions give strong practical guidance.

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

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

The description goes beyond the annotations (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?

The description is highly transparent about side effects: it generates AI content, waits, attaches a design, schedules the post, may consume credits, and can fail during scheduling while still returning a designId to avoid regenerating. It also mentions latency (30-180 seconds), optional image generation behavior, and plan/quota implications. This matches the annotations (readOnlyHint false, destructiveHint false, 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?

The description is well-structured and front-loaded with a one-sentence summary, followed by clarifications about designId, failure retry, and scheduling fields. It is somewhat long and repeats concepts also present in the schema, but the complexity of the tool justifies the length and the prose is organized and scannable.

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

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

The description provides sufficient context for what the tool does, how long it may take, what to do on failure, and how to supply required scheduling fields. Since the output schema is present, the lack of explicit return-value details is acceptable; the description still covers the important designId failure-return behavior.

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

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

The schema already covers 95% of parameters, and the description adds meaningful detail beyond the schema: it clarifies designId's role, explains postSettings reuse for reels, gives instructions for generateImages.context, and elaborates on responseType and videoSettings. Even nested parameters benefit from extra context such as the LinkedIn document/carousel distinction and TikTok requirements.

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

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

The description clearly states the tool's purpose: it generates a post with AI, waits for completion, then creates a scheduled post with the resulting design. It also distinguishes itself as a 'convenience tool' that combines generation and scheduling, and references the related postnitro_create_scheduled_post for the scheduling portion.

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

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

The description gives practical guidance on how to use the tool, including how to handle scheduling failures by retrying with postnitro_create_scheduled_post, and notes that scheduling fields should be provided exactly as they would be for that sibling tool. It could be more explicit about when to choose this over sequentially calling generate_and_wait and create_scheduled_post, but the convenience-tool framing makes the usage intent reasonably 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 that the tool polls until completion, returns the final output, and may take up to 180 seconds. It does not mention side effects such as credit consumption or that repeated calls may create multiple generations, but annotations do not contradict the described behavior.

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

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

The description is well-structured and includes several helpful usage notes, but it is somewhat long and repeats the 'optional if saved via defaults' point multiple times. Overall it remains focused and readable.

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 complexity of the nested parameters, the description covers key operational details such as polling, response types, image generation behavior, and failure best-effort outcomes. It does not describe the exact return shape, but the context indicates an output schema exists, so this is not a critical 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?

The description adds significant value beyond the schema, especially for generateImages.context by instructing the agent to author the brief itself and not ask the user. It also clarifies responseType 'DESIGN' behavior, image strategy and placement choices, and the paid-plan/quota/latency implications of image generation.

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 generates a carousel with AI, polls until completion, and returns the final output. It explicitly distinguishes itself from the single-image sibling tool, making its purpose and scope 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 useful usage context: it is a convenience tool that waits and returns output, may take 30-180 seconds, and notes where optional defaults apply. It points to an alternative for single-image posts, though it does not explicitly contrast with all related generation/scheduling tools.

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

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

The description discloses that the tool returns an embedPostId to track progress, implying asynchronous execution. It also references checking status and retrieving output, which further signals non-blocking behavior. However, it doesn't explicitly mention potential side effects like consuming credits or that it creates a persistent resource, but this is not required given 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, with four short sentences. It front-loads the core action, then provides the alternative, then parameter guidance, then workflow. No wordy or redundant content. Ideal length.

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 a complex schema with nested objects (e.g., generateImages), the description doesn't mention those details, but that's appropriate since the schema carries them. The description does cover the essential context: what it generates, how to track it, and when to use an alternative. It lacks a note about the optional image generation feature, but that's discoverable via the schema, so completeness is adequate.

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 provides descriptions for all parameters (coverage 86%), and the tool description does not add significant meaning beyond what's already in the schema. It mentions that some parameters are optional if defaults are saved, but that's already stated in the parameter descriptions. Thus, the description adds no extra semantic 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 description clearly states the tool's primary function: 'Generate a carousel post using PostNitro's AI engine.' It also distinguishes from a sibling by noting 'For a single-image post instead of a carousel, use postnitro_generate_image.' This leaves no ambiguity about what the tool does.

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

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

It explicitly provides guidance on when to use this tool vs. alternatives: 'For a single-image post instead of a carousel, use postnitro_generate_image.' It also explains the follow-up workflow: 'Use postnitro_check_status to monitor, then postnitro_get_output to retrieve. Or use postnitro_generate_and_wait for one step.' Additionally, it clarifies optional parameters: 'templateId, brandId, presetId, and responseType are optional if you've saved defaults via postnitro_set_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?

Discloses async behavior, that a trackable embedPostId is returned, and points to status/output retrieval. It does not mention credit consumption or possible failure modes, but the annotations do not contradict the described behavior and the readOnly/destructive hints are consistent with a generation tool.

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

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

Organized with purpose first, then alternative tool, then parameter guidance, then workflow. Each sentence earns its place and there is no filler or redundancy despite covering several operational details.

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 full lifecycle: create, get embedPostId, monitor, retrieve, and the wait variant. Since an output schema is present, the description need not spell out return fields, and it gives enough context for correct invocation.

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

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

Schema coverage is already high (86%), so the description adds limited new parameter-level detail. It usefully clarifies that slides are not provided for this tool, that IDs come from list tools, and that defaults can make optional fields unnecessary—reinforcing the schema without contradicting it.

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: 'Generate a single-image post (postType IMAGE) using PostNitro's AI engine.' It explicitly distinguishes this from postnitro_import_image and implies contrast with carousel/video siblings, so an agent knows exactly when to select it.

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 operational guidance: use postnitro_check_status then postnitro_get_output, or call postnitro_generate_image_and_wait for one-step. It also tells the agent to use list tools for valid IDs and explains optional defaults, leaving no ambiguity about how to proceed.

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 behavior beyond the annotations: it will poll until completion, may take 30-180 seconds, and the content is AI-generated from the prompt rather than supplied as slides. However, it does not mention side effects such as credit consumption, non-idempotency, or what happens on failure/timeout. With annotations all false and carrying little safety information, the description leaves some behavioral burden unmet.

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

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

Three short sentences/paragraphs, each earning its place: the first states purpose, scope, and latency; the second clarifies the content source and routes to the import alternative; the third covers optional defaults. The critical information is front-loaded 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 blocking generation tool with a rich input schema, an output schema, and a clear sibling alternative, the description covers the essential call flow, latency expectation, and default-saving behavior. It does not explain the optional generateImages object or failure handling, but the schema's detailed generateImages description and the output schema reduce the need for the main description to repeat them.

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

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

Schema description coverage is high (86%), so the schema already documents most parameter meanings. The description adds a useful consolidation that templateId, brandId, presetId, and responseType can be omitted when defaults are saved, and clarifies that aiGeneration is a prompt rather than slide content. This is helpful but not a substantial departure from the schema's own parameter descriptions.

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

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

The description opens with a specific verb and resource: it 'AI-generates a single-image post (postType IMAGE), polls until completion, and returns the final output.' This clearly identifies the tool's action, output, and blocking behavior, and distinguishes it from the import path by stating that content is AI-generated rather than user-supplied.

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

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

It gives an explicit alternative for the main competing case: 'To supply your own image content instead, use postnitro_import_image_and_wait.' It also notes that several parameters can be omitted if defaults were saved. It does not explicitly contrast with the non-waiting sibling postnitro_generate_image or with carousel tools, but the 'polls until completion' phrase and IMAGE postType make the intended use fairly 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?

Discloses asynchronous behavior (returns embedPostId for progress tracking), best-effort image generation with failure/completion notes, quota and plan requirements, latency impact, and audio ID validation semantics (rejects URLs/non-audio IDs). It also explains rendering limitations (cannot be PDF/PNG) and future reuse of videoSettings for reels.

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 detailed but every sentence serves a purpose, covering core action, async workflow, parameter nuances, and cross-tool references. The structure uses clear paragraphs and inline parentheticals that keep related information together without redundancy.

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

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

Given the output schema is present, the description still adds key operational context: that a returned embedPostId is used for tracking, how to check results and retrieve output, the distinction between DESIGN and MP4, and the conditions under which images may fail. This is sufficient for an agent to invoke the tool correctly.

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

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

Adds substantial meaning beyond the schema: explains that slides become scenes, clarifies videoDuration bounds and requirement, specifies audioId must be a media ID not URL, instructs the agent to author generateImages.context itself rather than asking the user, and details imageStrategy/imagePlacement behavior. This goes well beyond the raw property descriptions.

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

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

States the tool generates a video post via AI and returns an embedPostId, clearly distinguishing it from import-based video creation by noting it uses AI-generated scenes rather than user-supplied slides. It also mentions the postType VIDEO and contrasts with postnitro_import_video.

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

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

Provides explicit guidance on when to use which responseType, when videoSettings is required, and references related tools for defaults, listing, status checking, and retrieval. It also names the synchronous alternative postnitro_generate_video_and_wait, making usage conditions 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 behavioral details beyond annotations: it waits and polls, has typical latency, may still complete if image generation fails, consumes AI-image quota, and requires specific conditions for MP4 rendering. This aligns with the annotations (non-destructive, non-idempotent) without contradiction.

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

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

The description is well-structured, front-loaded with the core purpose, and each paragraph adds value covering distinct aspects: latency, AI generation vs import, output types, and optional defaults. Despite length, it is not verbose and every sentence serves a purpose.

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

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

Given the tool's complexity (nested objects, many optional parameters), the description is thorough. It explains the waiting behavior, output options, image generation fallback, and how to check status via postnitro_check_status. Together with the rich schema, it provides enough context for an agent to use the tool effectively.

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

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

The input schema already covers most parameters with descriptions (coverage 88%). The description adds extra clarifications such as 'A video cannot be rendered as PDF or PNG' and the relationship between responseType and videoSettings, which go slightly beyond the schema and aid understanding.

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 primary function: AI-generates a video post, polls until completion, and returns the final output. It also distinguishes itself from the import tool, making the purpose unambiguous.

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

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

The description explicitly contrasts with postnitro_import_video_and_wait, advising to use this tool for AI-generated content and the import tool for custom slides. It also explains the trade-offs between DESIGN and MP4 response types and mentions optional defaults, giving clear guidance for selecting this tool over 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?

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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds concrete behavioral details: what fields are always returned, what fields are conditionally present for PDF/PNG/MP4, and that DESIGN output omits rendered file fields. This gives the agent a clear expectation of the tool's 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?

The description is a single, well-structured paragraph that covers all necessary aspects without redundancy. Each clause adds meaningful information (what is returned, when it applies, and the conditional output), and no irrelevant details are included.

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 (one parameter, simple output), the description is complete. It explains the purpose, the input, the output structure, and the edge case (DESIGN output). The agent has everything needed to invoke this tool correctly without ambiguity.

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 sole parameter embedPostId is described as 'The embed post ID of a completed post', which adds contextual meaning beyond the simple type. Since schema coverage is 100% and the description enriches the parameter's purpose, it exceeds the baseline.

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

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

The description clearly states the verb 'Retrieve' and the resource 'generated output for a completed post'. It distinguishes itself from sibling tools by explicitly mentioning the always-returned designId and editorUrl, and the conditional rendered file data, making its purpose unambiguous.

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

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

It specifies the condition 'for a completed post', which tells when this tool is appropriate. It also clarifies that for DESIGN output no rendered file is returned, preventing misuse. This effectively guides selection among related tools like check_status or get_scheduled_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?

The 'Fetch' language aligns with the readOnly/idempotent/non-destructive annotations, and the description adds useful context about the returned fields such as captions, social accounts, platform settings, design details, and publishing status.

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 concise sentence with no redundant content, front-loading the core operation and then listing the relevant returned details.

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

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

For a simple read operation with one parameter and existing annotations, the description fully captures what the tool returns and how to identify the target post. No important context is missing.

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

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

The only parameter, scheduledPostId, is a required string with a clear description and a source instruction to obtain it from list_scheduled_posts. Schema coverage is complete and the description of the parameter is helpful.

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 it fetches a single scheduled post by ID and enumerates the returned data, distinguishing it from sibling list/create/update/delete operations.

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

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

The parameter description explicitly tells the agent to get the ID from postnitro_list_scheduled_posts, which provides practical usage guidance. It does not explicitly name alternative tools, but the single-post fetch intent 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 annotations already declare readOnly, idempotent, and non-destructive behavior, and the description does not contradict that. However, the description adds no extra behavioral caveats such as side effects, auth requirements, or rate limits beyond what the annotations already provide.

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

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

The description is a single, focused sentence with no redundant words. The key verb, object, and distinguishing output details are front-loaded, making it easy to scan and understand quickly.

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?

Because an output schema exists, the description does not need to enumerate every return field, and it still highlights the most meaningful output characteristics. The input provenance is also present, so the agent has enough context to call the tool successfully.

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 only parameter, socialAccountId, is fully described and includes its source from postnitro_list_social_accounts, which is helpful provenance. Since the schema covers 100% of parameters, the description does not need to compensate for missing 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 states the specific action 'Fetch' and the precise resource: a single connected social account identified by ID. It also names the distinguishing output details (scheduled-post status breakdown and token expiry), which separates it from list-oriented siblings like 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?

The parameter description provides useful context by telling the agent to get the ID from postnitro_list_social_accounts, and 'single... by ID' implies this is for one-account lookups. It does not explicitly enumerate when-not-to-use alternatives such as listing all accounts or disconnecting an account, so it stops short of fully explicit guidance.

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

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

Annotations indicate the tool is not read-only and not destructive, and the description matches by explaining it creates a design and then a scheduled post. It goes beyond annotations by disclosing the 15–60 second wait, the failure behavior and designId reuse path, the paid-plan requirement for AI images, quota consumption, added latency, and the best-effort nature of image generation. No behavioral contradictions with the annotations exist.

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

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

The description is front-loaded with the core purpose and then provides necessary orchestration details, failure handling, and per-postType guidance. It is long but every section serves a real instructional need; minor redundancy (e.g., repeating the scheduling-fields instruction) keeps it from being perfectly concise.

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

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

Given the tool's complexity and the existence of an output schema, the description covers the essential context: the import-then-schedule workflow, how to avoid re-importing on failure, which sibling tools to consult first, defaults for optional parameters, video settings fallback behavior, and AI image generation caveats. No critical usage context appears missing.

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

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

The schema already covers 100% of parameter descriptions, including the slide vs. slides distinction, videoSettings vs. postSettings, and responseType. The tool description mostly restates these relationships rather than adding new parameter-level meaning. It adds some high-level orchestration context, but per the rubric baseline for full schema coverage, this is adequate but not exceptional.

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 this is a convenience tool that imports content, waits for it to finish, then creates a scheduled post attaching the resulting design. It distinguishes itself from sibling import and scheduling tools by naming the mirrored tools (postnitro_import_carousel / postnitro_import_video / postnitro_import_image) and postnitro_create_scheduled_post, so an agent knows exactly what this composite operation does.

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

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

The description gives explicit, actionable guidance: which postType maps to which slide input, that postnitro_get_import_template should be called first, that optional parameters can come from defaults, and that if scheduling fails after import the returned designId can be reused with postnitro_create_scheduled_post without re-importing. It also tells the agent to provide scheduling fields exactly as in postnitro_create_scheduled_post, leaving no ambiguity about when to use this tool.

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

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

Description discloses important behavior beyond annotations: polling until completion, 15-60 second latency, optional defaults, strict slide rules, and detailed best-effort behavior of image generation including quota consumption and failure handling. 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?

The description is long but well-organized with a summary, an IMPORTANT prerequisite callout, and numbered strict rules. It front-loads the core purpose and then provides necessary details for a complex 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 the tool's complexity, the description covers purpose, prerequisites, parameter behavior, polling, latency, and failure handling. Since an output schema exists, not detailing return values is acceptable, and the description is otherwise complete enough for correct use.

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 high, but the description adds meaningful usage context around slide ordering, layout constraints, and the generateImages context requirement. This supplements the schema descriptions without redundancy issues.

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 states exactly what the tool does: imports custom slide content, polls until completion, and returns the final output. It also distinguishes itself as a convenience wrapper with a wait-and-return behavior, separating it from sibling import 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 clear guidance on prerequisites (call postnitro_get_import_template first) and optional parameters if defaults are saved. It also specifies strict structural rules for slides. It does not explicitly enumerate alternatives like postnitro_import_carousel, but the wait-for-output behavior is clearly 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 indicate non-readonly, non-destructive, non-idempotent behavior. The description discloses additional side effects: generateImages consumes AI-image quota, adds latency, and may fail gracefully. It also explains responseType options and their performance implications, providing full transparency without contradicting 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 lengthy but well-organized: a clear one-sentence purpose, an IMPORTANT callout, a numbered list of strict rules, and a concise minimal example. Every section earns its place given the complexity of the tool's input; it is not padded or redundant.

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

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

Given the tool's complexity (6 parameters, nested objects, enums, optional configurations), the description covers all essential usage aspects: prerequisite call, structural rules, output format choices, image generation behavior, and fallback handling. The minimal example anchors the concept. Nothing critical is missing for an agent to use the tool correctly.

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

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

Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds value by illustrating the slides array structure with an example and highlighting key constraints (slide types, column count, cycle behavior), which helps agents understand how to populate nested fields correctly. This goes slightly beyond the schema alone.

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 ('Create') and resource ('carousel'), and clarifies the method ('importing your own slide content'), which distinguishes it from generation tools like postnitro_generate_carousel. The purpose is immediately clear.

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

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

Provides explicit 'IMPORTANT' instruction to call postnitro_get_import_template first, enumerates strict structural rules, includes a minimal example, and notes optional parameters when defaults are saved. This gives the agent practical, unambiguous guidance on how and when to use the tool.

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

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

The description discloses behavioral aspects beyond the annotations: it indicates the operation is asynchronous ('Returns an embedPostId to track progress') and suggests using check_status to monitor completion. It also mentions the alternative '_and_wait' for synchronous blocking. However, it does not explicitly state that the operation is not idempotent or that it may consume credits, though annotations already imply non-idempotence.

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 moderately lengthy but each sentence is purposeful. It is structured logically: first the main purpose, then the contrast with carousel, then notes on optional defaults, and finally the workflow. No redundant or filler content is present, though it could be slightly more concise without losing critical details.

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

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

For a tool with a nested object schema and multiple optional parameters, the description is highly complete. It covers the core usage, the distinction from siblings, the asynchronous workflow, and the conditions under which parameters can be omitted. It also mentions the 'generateImages' feature and its implications (requires paid plan, consumes quota, adds latency), which is important context for the agent.

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

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

The description adds significant semantic value beyond the schema. It clarifies that 'slide' must be a single object, not an array, and that only 'heading' is required. It explains the 'infographic' layout type and its relationship to carousel infographics, and notes that 'responseType' defaults to 'DESIGN' for faster operation. This directly resolves ambiguities present in the schema.

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

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

The description clearly states the tool's purpose: 'Create a single-image post (postType IMAGE) from one slide of your own content.' It explicitly distinguishes it from carousel posts and explains the key difference (single object vs array). It also mentions the return of an embedPostId for tracking, reinforcing the core function.

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: it contrasts with carousel usage, explains when to use this vs. the '_and_wait' variant, and mentions that parameters like templateId, brandId, and responseType can be omitted if defaults are saved. It also directs users to postnitro_check_status and postnitro_get_output for monitoring and retrieval, giving a clear workflow.

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 it polls until completion, may take 15-60 seconds, and returns the final output. It also mentions optional AI image generation behaviors (best-effort, quota, latency) without contradicting 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 well-structured: a concise opening summary, then important clarifications. It avoids redundancy with the schema and keeps the essential usage notes front-loaded. Length is appropriate for the tool's complexity.

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

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

The description, combined with the detailed schema, provides complete information for an agent to decide when to use this tool and what to expect. It covers waiting behavior, default handling, and the single-image scope, while the schema covers all parameter specifics.

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

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

The description adds valuable clarifications beyond the schema, such as passing slide as a single object (not an array), the infographic layout support, and that templateId/brandId/responseType are optional if defaults are saved. This complements the schema's thorough field descriptions.

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

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

The description clearly states it creates a single-image post from one slide, polls until completion, and returns the final output. It distinguishes from sibling tools that handle carousels, videos, or non-waiting imports.

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 mentions 'single-image post' and 'polls until completion', indicating when to use this instead of the carousel/video or non-waiting variants. It also notes the optional defaults from postnitro_set_defaults and the waiting latency.

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 tool returns an embedPostId, tracks progress, and supports DESIGN vs MP4 output, which goes beyond the annotations. It does not contradict the readOnly/destructive/idempotent hints, and while it doesn't mention credit consumption, the async tracking info is sufficient.

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 well-structured and each sentence adds value, but it is somewhat long with multiple paragraphs. It could be slightly more condensed without losing important details, yet it remains efficient and readable.

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

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

The description covers the core action, output types, defaults, monitoring workflow, and alternative one-step tool. It gives an agent everything needed to decide when and how to use this tool correctly, including the slide-array relationship to carousels and infographic layouts.

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

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

The input schema already covers all parameter descriptions at 100% coverage, so the baseline is 3. The description adds a few high-level reminders (e.g., videoSettings required for MP4, defaults optional) but does not provide substantial new parameter semantics beyond what the schema already states.

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

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

The description clearly states the tool creates a video post from user-provided scene content, using a specific verb and resource. It distinguishes itself by emphasizing 'own scene content' (import rather than generate) and explains the slide structure clearly.

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 tells the agent to use postnitro_check_status and postnitro_get_output for monitoring/retrieval, and points to postnitro_import_video_and_wait as a one-step alternative. It also notes that templateId/brandId/responseType can be omitted if defaults are saved, giving clear when-to-use guidance.

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

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

The description discloses important behaviors such as polling until completion, rendering latency, the need for videoSettings when MP4 is requested, and reliance on saved defaults for optional parameters. It does not exhaustively cover failure or partial-completion behavior, but the main behavioral contract is clear.

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 organized in clear paragraphs and front-loads the core purpose. It repeats a little of the schema information, but the extra context is relevant and not overly verbose.

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

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

Given the nested objects and multiple optional settings, the description provides enough high-level context to understand the tool's role and key constraints. It relies on the schema for detailed nested structures, which is appropriate.

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 has high coverage, and the description adds extra meaning by clarifying scene/slide equivalence to carousel slides, the exact slide type counts, output modes, and how saved defaults affect optional parameters. This helps the agent understand the data model and requirements.

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

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

The description clearly states that the tool creates a video post from user-provided scenes, polls until completion, and returns the final output. It also distinguishes this from carousel generation by explicitly mentioning postType VIDEO and the scene/slide structure.

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

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

The description gives useful context on when to use this tool: it is a convenience tool that waits for completion, describes the expected rendering time, and explains the difference between DESIGN and MP4 outputs. It does not explicitly name alternative non-waiting tools, but the usage 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?

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 indicate readOnlyHint, idempotentHint, and destructiveHint false. The description adds helpful context about not uploading audio, what an empty list means, and how to present matches to the user, though it does not go into side effects or system behavior 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 front-loaded with the core purpose and then provides concise, non-redundant usage guidance. Each paragraph adds distinct value: what the tool lists, how to use it for `audioId`, and how to handle empty or ambiguous results.

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 exists, the description does not need to detail return values. It covers key contextual points including the relationship to video/reel settings, the prohibition on URLs, the upload workflow, and user-facing handling of search results, making it complete 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 schema already provides 100% coverage for both parameters (`page` and `limit`) with clear descriptions including defaults and max. The description adds no additional parameter-specific semantics, so a baseline score 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: 'List the audio files in your workspace, newest first.' It also distinguishes this from sibling tools by focusing on audio resources and explicitly ties the tool to resolving an `audioId` for video and scheduled reel settings.

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

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

The description explicitly says when to call this tool ('Call this to resolve an `audioId`'), gives behavioral guidance for empty results ('ask the user to upload some in the app, and create the video without audio in the meantime'), and clarifies that this API does not upload audio, setting appropriate expectations.

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 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 mark it as read-only and idempotent. The description adds useful behavioral detail that all platform arrays are always present, even when empty.

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 concise, well-structured, and directly communicates the tool's purpose and output behavior 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?

Provides enough context for an agent to know when to call it and what to expect, including the always-present empty arrays. Lacks a detailed output schema, but the simple grouped-list behavior is sufficiently described.

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

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

The tool has no parameters, and the description accurately reflects that. No parameter explanation is 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?

Clearly states the tool lists connected social accounts grouped by platform, and distinguishes the account IDs as the values used for selectedAccounts in scheduled post creation.

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

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

Explains when the returned IDs are needed (for creating scheduled posts) and notes the grouping. It does not explicitly contrast with get_social_account, but the purpose is clear 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 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.

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

The description explicitly states that the update REPLACES captions and accounts, disclosing destructive behavior beyond the annotations. It also mentions the need to send the full state, which is useful behavioral detail. No contradiction with annotations.

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

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

The description is two concise sentences, front-loading the core behavior and a key tip. No unnecessary words or redundancy.

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

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

Given the schema's high coverage, the description does not need to repeat parameter details. It adds the essential context of replace semantics and a retrieval tip, making it sufficient for an agent to correctly invoke the 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 schema descriptions already cover 100% of parameters, so the baseline is 3. The tool description adds a general note about replace semantics and a tip, but does not provide additional parameter-specific meaning beyond the schema.

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

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

The description clearly states the tool updates an existing scheduled post or draft, with a specific verb and resource. It also distinguishes itself by mentioning it mirrors the create tool, making its purpose unambiguous.

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

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

It provides guidance on when to use it (updating vs. creating) and includes a practical tip to call the getter first. It does not explicitly name alternative tools but clearly implies the update counterpart to the create tool.

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