Post Kit

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), it discloses the key behavioral constraint that only supplied facts are used, and explicitly rules out publishing, account reads, and trend/statistics fetching. It also previews the return payload, so the agent knows the call is a pure drafting operation with no side effects.

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

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

The trigger, inputs, outputs, and exclusions are front-loaded in a single dense paragraph with essentially no filler. It reads as one long run-on sentence, which slightly hurts scannability but wastes nothing.

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

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

For a 3-parameter drafting tool with full schema coverage and an output schema, this is complete: the agent knows the inputs, the per-platform output shape (length, hashtags, rule pass/fail, checklist), and the operational limits. Nothing needed to invoke it correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it tells the caller to pack 'every fact and any link' into the topic, notes the tone is optional, and restates the 1-to-6 platform bound. That clarifies how to populate the free-text topic in a way the schema cannot.

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

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

States a specific verb+resource ('draft/write social posts') scoped per platform, with a concrete user-intent example. It is clearly distinguishable from siblings like draft_video_script or draft_tiktok_slides, which target single formats rather than one draft per platform.

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?

Opens with an explicit trigger ('Use this when the user wants social posts written about a topic') plus a sample invocation, and implicitly bounds scope by saying it does not publish, read accounts, or fetch trends. It never names a sibling alternative for overlapping cases, so it stops short of a full when/when-not routing statement.

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

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

Annotations already establish the safe, idempotent, non-destructive read profile, and the description adds real context beyond them: 'It does not publish or store the idea', 'One call is one plugin-call', and an explicit size warning (~400 KB for 20 slides) that affects how the agent should request images. It also tells the agent to quote the summary field first and to only persist PNGs when asked, which is useful operational guidance.

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 invocation guidance is front-loaded, but the body drifts into loosely ordered asides ('Stake is the second pain beat', 'The same page is at /slides') that interrupt the otherwise useful flow. Several return-format sentences restate what the output schema already carries, so not every sentence earns its place.

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

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

For a 5-parameter generation tool with an output schema and full annotation coverage, the description covers triggering, defaults, parameter interactions, side effects (no publish/store) and output handling well. Minor gaps remain around how a returned posting plan is shaped and what the /slides page offers, but nothing an agent needs to invoke it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining cross-parameter behavior the schema only hints at: with angle_lines the supplied lines replace the fixed frames and the angle count derives from the array, and images only matters alongside angle_lines. It also flags that stake is the second pain beat, which is not in the schema.

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

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

States a specific verb and resource ('make TikTok slideshows') and a concrete triggering scenario ('test an app idea with TikTok slideshows before coding'), so an agent can distinguish it from a generic post or video-script tool. It never names its nearest siblings (draft_posts, draft_video_script) to sharpen the boundary, so it stops short of a 5.

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

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

Gives explicit invocation conditions and a sample utterance ('make 4 slideshows for this idea'), plus conditional guidance: pass angle_lines 'for a product or a new account', pass plan_days for a posting plan. No exclusions or named alternatives are provided, so the agent has context but no hard routing rule.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description goes further by stating it uses only the supplied facts, that no publishing or video generation occurs, and that platform rules are checked. It does not mention cost, latency, or failure modes, but the added constraints are meaningful beyond the annotations.

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

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

Front-loads the trigger and example, then the return shape, then the exclusions. It is dense and partially a run-on, but every clause carries information (timing clock, caption per platform, ai_disclosure block).

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

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

An output schema exists, so enumerated return values are somewhat redundant, but the description still covers the timing structure, per-platform caption rules, and AI-disclosure behavior. Exclusions and scope are complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents topic, platforms, and tone, including the AI-disclosure instruction. The description reinforces the topic/facts and platform list but adds no syntax or format detail beyond the schema, and never mentions the optional tone parameter.

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

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

States a specific verb and resource (write a script for a short vertical video) plus the exact output artifacts. It clearly differentiates itself from draft_posts and draft_tiktok_slides by scoping to a timed short-form script with per-platform captions and AI disclosure.

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?

Opens with an explicit trigger ('Use this when the user wants a script for a short vertical video') and a concrete example request. It also names what the tool will not do (does not publish, make the video, clone voices, write for fake-identity accounts), giving clean when-not boundaries.

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, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the tool is pollable (pending until a reply arrives, then answered) and carries an explicit trust boundary warning that reply content is data, not instructions — a meaningful prompt-injection disclosure.

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

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

Three tight sentences: purpose first, then polling behavior, then the trust caveat. Every sentence carries distinct information and nothing is padded.

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

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

For a single-parameter read tool with an output schema and full annotation coverage, nothing an agent needs is missing. The polling semantics and the injection warning go beyond what structured fields provide, closing the remaining gaps an agent would otherwise have to discover by trial.

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

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

Only one parameter exists and the schema already documents it fully (coverage 100%, including the ^fb_[0-9a-f]{32}$ pattern and the note that submit_feedback returned it), so the baseline of 3 applies. The description repeats the ticket-id linkage but adds no format or validation detail beyond the schema.

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

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

States a specific verb (Read) and resource (maintainers' reply to feedback), and ties it causally to the sibling tool submit_feedback via the ticket id. An agent can distinguish it from submit_feedback, screen_token, and wallet_identity without opening any schema.

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

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

Clearly establishes the precondition: this is used after submit_feedback, with the ticket id that call returned. It does not state any exclusions or alternative ways to retrieve feedback status, but the usage context 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 readOnly/idempotent/non-destructive, but the description adds substantive behavior the annotations cannot express: it reads exactly one public page, honours robots.txt, copies no images, runs no scripts, and 'does not render a video file'. Those are the exact constraints an agent needs to set user expectations.

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

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

Front-loaded with the trigger condition and example, then a dense but useful enumeration of outputs and constraints. Slightly redundant with the schema in the 'Pass the page address' sentence, but no padding overall.

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 one-parameter generation tool, the description covers trigger, inputs, output shape, and hard behavioral limits; an output schema exists, yet the description still usefully summarizes the return surface. Nothing needed to invoke it correctly is absent.

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

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

Schema coverage is 100% and the url parameter is already documented with format and the public-sites-only constraint. The description only restates 'Pass the page address' and adds the single-page read limitation, adding little beyond the structured field.

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

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

Names a specific verb and artifact: builds a self-contained HTML page containing an animated CSS clip of about 12 seconds, and enumerates the content it includes (name, headline, description, up to three headings, call to action). It also draws a hard boundary against a plausible sibling output by stating it 'does not render a video file', so an agent can tell it apart from a script-producing tool.

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

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

'Use this when the user wants a short launch video for their own product page' gives explicit trigger context plus a concrete example invocation. It stops short of naming alternatives or exclusions (e.g. when to prefer draft_video_script), so it's clear context without routing rules.

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

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

Annotations only cover the safety profile (readOnly, non-destructive, open-world, non-idempotent). The description goes well beyond them by explaining the adaptation behavior — tone, idioms, examples and formats rather than word-for-word translation, no new claims added, and no publishing — which is exactly the kind of semantic disclosure annotations cannot carry.

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

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

Front-loaded with the trigger condition, then inputs, then return shape, then behavioral caveats. Every sentence carries information an agent needs; nothing is padding.

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

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

An output schema exists, and the description still succinctly previews the return shape (adapted text, language, change list, platform check), so the agent knows what to expect. For a read-only 3-param tool with full schema coverage and annotations, nothing material is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, including the enum and the 'do not paste other people's posts' constraint. The description's 'pass the post text, the target market and optionally a platform to check the result against' largely restates the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource — adapting the user's own post for another country/language — with a concrete example ('adapt this for a Japanese audience'). It is clearly distinguishable from drafting siblings like draft_posts, since the input is the user's existing text rather than a new draft.

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

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

Gives an explicit triggering condition ('when the user wants a post they wrote adapted for readers in another country or language') plus a boundary ('Only for the user's own text; it does not publish'). It does not name a sibling alternative for the adjacent case of drafting fresh content, but the when-to-use condition 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 readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: it draws no picture, publishes nothing, stores nothing, title/subtitle/byline remain live text, and the returned spec lets the user move the title, scale the subject and export PNGs without regenerating. These are exactly the behavioural traits annotations cannot express.

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

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

Front-loaded with the trigger, and nearly every clause carries information (derivation rules, defaults, return contents, limits). It is, however, a single dense run-on paragraph with long compound sentences, which makes it harder to scan than a short bulleted structure would be.

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 picture an agent needs: when to invoke, required vs optional inputs, derivation defaults, format defaults, the shape of the return, and explicit non-actions (no drawing, publishing or storage). With annotations carrying the safety profile and an output schema present, nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic guidance beyond the schema: derive title from the idea if omitted, supply a concrete subject because an idea alone yields a vague picture, and it enumerates the optional fields in one place. Minor tension: title is required in the schema yet the description frames it as derivable when omitted.

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

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

States a specific verb and resource ('make a layered post cover') and precisely delimits what it produces: a cover spec JSON with ordered layers, pixel positions, image prompts, SVG and a canvas link. That is clearly distinguishable from siblings like draft_posts or draft_video_script without opening any schema.

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

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

Opens with an explicit trigger ('Use this when the user wants a cover image for a post, article, note or product') and an example utterance, so the invocation condition is clear. It does not, however, name a sibling alternative (e.g. draft_posts for text-only output) or state when not to use it, so routing against alternatives is left to inference.

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

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

Adds substantial context beyond the annotations: it returns a ticket id, feedback is explicitly not a chat and nothing in it is executed, and links/emails/phone numbers are stripped with nothing stored about the caller. That privacy and no-execution disclosure is genuinely useful given openWorldHint=true and readOnlyHint=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?

Front-loads what the tool sends, then what to pass, then what it returns, in three dense sentences with no filler. Every clause carries actionable information.

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

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

Covers purpose, the enumerated kinds, the optional tool/error inputs, the 1000-character bound, the return value (ticket id), and privacy handling. With an output schema present, nothing further is required 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?

Schema description coverage is 100%, so the schema already documents all four parameters including the kind enum. The description restates the message length limit and the optionality of tool/error ('if you know them') but adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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

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

States a specific verb and resource ('Send feedback, a bug report or a tool request to the maintainers of the tools on this server') and enumerates the concrete situations (missing tool, stale data, broken/wrong answer). It is clearly distinguishable from the read-side sibling get_feedback_reply.

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 triggering conditions for each kind (need_tool, need_data, bug, other) and tells the agent to include the tool name and error text when known. It does not explicitly name the alternative get_feedback_reply or state when NOT to use this tool, so it falls short of full routing guidance.

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