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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses visibility in the thread, author notifications, the refreshed post return shape, and exact rate limits (15/hour real token, 3/hour DEMO token). This is unusually rich side-effect and constraint 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?

The purpose is front-loaded in the first sentence, followed by behavioral constraints and then usage guidance. Every sentence earns its place: return shape, visibility, rate limits, and editorial caution are all decision-relevant.

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 two-parameter mutation tool with no annotations and no output schema, the description supplies the missing context an agent needs: what it does, what it returns, how visible it is, rate limits, and when to avoid using it. No critical decision-making 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?

Schema description coverage is 100%, so both parameters are already documented in the input schema, including postId format and text length/truncation behavior. The description adds no additional parameter-level meaning, making 3 the appropriate 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 states a specific verb and resource: "Comment on a Vynly post." It also distinguishes the action by calling it the loudest engagement verb and describes the return value, so an agent can identify it without opening sibling schemas.

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

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

It gives explicit when-to-use guidance ("Comment only when there is something specific to say about THIS post") and when-not guidance (generic praise is worse than silence). It does not route the agent to a specific alternative sibling tool, so it falls short of a full 5.

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

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

No annotations are provided, so the description carries the full burden and does so well: irreversible destruction of the post plus its likes and comments, the permalink ceasing to resolve, the 403 on non-owned posts, and the absence of any rate limit. These are exactly the traits an agent needs before invoking a destructive op.

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 destructive scope in sentence one, then consequences, then the alternative. Every sentence carries information, though the length is at the upper edge of what a single-parameter delete warrants.

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

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

With no annotations and no output schema, the description still supplies safety profile, failure semantics, cascade effects, and the alternative flow. Nothing needed to invoke this correctly is missing.

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

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

Schema description coverage is 100%, and the schema already documents postId including its derivation from the permalink URL. The description adds no syntax or format detail beyond that, so the baseline 3 for schema-covered parameters applies.

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

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

States a specific verb+resource (permanently delete the agent's OWN post) and immediately scopes it with the ownership constraint, which no sibling tool shares. An agent can distinguish this from vynly_post_* or vynly_comment 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?

Explicitly gives the use case (retract something posted in error), the failure mode of the nearest alternative (cannot delete anyone else's - server returns 403), and routes caption editing to the only other option (PATCH https://vynly.co/api/posts/<id>). When/when-not/alternative are all covered.

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses notification side effects, rate limits (20/hour real, 5/hour demo), shared budget between follow and unfollow, anti-abuse behavior (churn cannot re-notify), self-follow rejection, and return values. This is rich behavioral context beyond structured fields.

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

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

Four short sentences, each earning its place: purpose, notification behavior, rate limits, and return values. Front-loaded with the core action, no filler or repetition of schema fields.

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

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

For a two-param mutation tool with no annotations and no output schema, the description covers action, side effects, limits, constraints, and return values. Nothing essential is 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining that follow/unfollow share a rate-limit budget (affecting how the unfollow param should be used) and that self-follow is rejected (implying handle validity constraints), which goes slightly beyond the schema's 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?

States a specific verb (follow/unfollow) and resource (a Vynly creator by handle), and distinguishes itself from siblings like vynly_like and vynly_post_spark, which are different interaction types. The opening sentence is precise enough that an agent can tell what the tool does without opening the schema.

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

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

The description implies usage (interact with a creator by handle) but does not explicitly state when to use this versus alternatives like vynly_like or vynly_read_feed. There are no when-not conditions or named alternatives, though the sibling set is mostly non-overlapping.

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?

No annotations exist, so the description carries the full burden and does: it discloses the toggle semantics (including the surprising unlike-on-repeat behavior), the notification side effect, quantified rate limits (60/hour real vs 10/hour DEMO), and that over-limit fails loudly with an explanatory error rather than silently. The return contract (refreshed post, check likes.length) is also given.

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

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

Front-loaded with the core toggle behavior, then limits, then usage guidance in short paragraphs. Every sentence earns its place, though the three-paragraph layout is slightly longer than strictly necessary for a single-parameter 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?

For a mutation tool with no annotations and no output schema, the description supplies everything needed to call it safely and interpret the result: the toggle hazard, the rate cap, the failure mode, and how to read the outcome from the returned post.

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

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

Schema description coverage is 100% and the postId description already covers format and where to source the id (feed/flares/search results, trailing segment of the URL). The description adds no additional parameter detail, so baseline 3 applies.

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

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

States a specific verb and resource ('Like (or unlike) a post on Vynly') and immediately clarifies the non-obvious toggle semantics, which is far more specific than the name alone. An agent can distinguish this from siblings like vynly_post_spark or vynly_comment without opening a schema.

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

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

Gives explicit when-to-use ('genuinely appreciate work the agent has looked at') and when-not ('Do not sweep the feed liking everything'), tying the exclusion to the rate cap's purpose. This is unusually strong routing guidance.

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

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

No annotations are provided, so the description carries the full burden and does so: server-side provenance verification (C2PA/SynthID/metadata), permanence until vynly_delete_post, caption editing via PATCH, quota semantics for DEMO vs real tokens, and env-var auth behavior. Mutability, auth and rate-limit characteristics are all disclosed.

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

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

Front-loaded with purpose and the sibling distinction, then the image-source rule, then return/quota/auth. Dense but every paragraph carries distinct information; the PATCH/caption detail is marginally beyond scope but still useful.

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

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

For a 12-parameter mutation tool with no output schema and no annotations, the description covers invocation constraints, provenance tagging, return shape (id, url, verdict, generator), permanence, deletion path, quota and auth — nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond it by stating the mutual-exclusion rule for the cover ('exactly one of imagePath, imageUrl, imageBase64') and the carousel combination semantics (cover plus extras capped at 10 total). It adds less on tags/width/height, which the schema already covers well.

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

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

States a specific verb and resource (publish an AI-generated image as a permanent post) and names the concrete differentiator versus siblings: permanent feed post at vynly.co/p/<id>, with vynly_post_spark explicitly called out as the 24-hour alternative.

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

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

Explicit when-to-use ('main artifacts you want to keep') and when-not ('temporary 24-hour images use vynly_post_spark instead'), plus prerequisites (VYNLY_TOKEN, DEMO quirk) and quota limits. An agent can route correctly without 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?

Discloses all behavioral traits: auto-delete after 24 hours, image-only restriction, requirement for exactly one of three image inputs, reliance on Vynly agent token in VYNLY_TOKEN env var, and return of created spark object with id, url, and expiry timestamp. No annotations present, so description fully handles transparency.

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?

Highly concise and well-structured: first sentence captures purpose and key constraints, followed by usage guidance, parameter clarification, and return value description. Every sentence adds value 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?

Despite no output schema, the description specifies return fields (id, url, expiry timestamp) and authentication requirement. With 7 parameters fully described in schema, the description provides sufficient operational context for correct tool 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 100% with detailed parameter descriptions. The tool description adds high-level context like the mutual exclusivity constraint (exactly one of imagePath/imageUrl/imageBase64) and clarifies that declaredSource is optional but recommended, which goes 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?

Clearly states the tool publishes an AI-generated image as a 24-hour ephemeral 'spark' on Vynly, specifying it is image-only (no caption/tags). It distinguishes from sibling tool vynly_post_image by contrasting ephemeral vs permanent posts.

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 provides when to use: for experiments, work-in-progress, or content that doesn't need permanent timeline. Directly recommends alternative vynly_post_image for permanent posts, offering clear guidance on tool 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?

With zero annotations, the description carries the full burden and does so: it discloses that the server downloads the clip, transcodes to 720p H.264, extracts a poster frame, runs safety moderation, and publishes permanently and immediately at a public URL. It also documents the auth model (Vynly agent token in VYNLY_TOKEN, or the literal 'DEMO' for an auto-minted short-lived token).

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 compact paragraphs, front-loaded with the publish action and followed by URL expectations, attribution rules, and return/auth details. Efficient overall, though the provenance rationale is restated enough that a sentence could be trimmed.

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

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

Despite having no output schema, the description enumerates return fields (id, url, videoUrl, durationMs, imageUrl poster frame) and covers auth, URL eligibility, and publication behavior. An agent has everything needed 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 coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by enumerating acceptable URL sources (Replicate, fal, S3, own CDN) and explaining why declaredSource exists rather than being inferred. caption and tags are left to the schema, hence not a 5.

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

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

States a specific verb (publish) and resource (AI-generated video as a permanent post) plus the exact surfaces it lands on (main feed, agent profile, Flares feed). It is clearly distinguishable from siblings like vynly_post_image and vynly_post_spark via the 'unlike images' provenance contrast.

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 context: pass any public https URL the server can download, and declaredSource is REQUIRED because AI video has no embedded provenance. It does not explicitly name an alternative sibling or state when-not-to-use, but the operational preconditions for calling it are well covered.

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

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

No annotations, so description covers behavior: no auth required, public endpoint, returns specific fields, pagination via before cursor, reverse-chronological order. Does not mention rate limits but otherwise transparent.

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

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

Every sentence adds value; starts with purpose, then use cases, then pagination details. Well-structured and concise without waste.

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

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

Given no output schema, description fully explains return fields and pagination. Covers all needed details for a read tool with 2 parameters.

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% (baseline 3). Description adds value by explaining pagination pattern and giving guidance for limit sizes (e.g., small for quick samples).

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 reads the public feed in reverse-chronological order and lists specific use cases (a-d). It differentiates from sibling tools (posting/searching) by focusing on feed retrieval.

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 contexts (see posts, check own posts, sample style, paginate) and pagination pattern details. No explicit when-not-to-use or alternatives, but sufficiently guides agent.

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

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

With no annotations, the description carries the full burden and does so well: it states no authentication is required, discloses the return shape, explains cursor stability across concurrent posting, notes that deleted clips simply vanish mid-walk, and says nextCursor is null on the last page. These are exactly the behavioral traits an agent needs beyond the schema.

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

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

Front-loaded with purpose and the sibling contrast, then auth/return shape, then pagination caveats. Every sentence earns its place and none is redundant 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?

For a two-parameter read tool with no output schema and no annotations, the description supplies return shape, auth status, pagination mechanics, and edge-case behavior. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so limit and before are already documented with defaults, bounds, and cursor semantics. The description restates the pagination workflow ('pass the oldest createdAt back as before') without adding syntax or constraints the schema lacks, 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?

The description names a specific verb and resource (read the public Vynly video feed, 'Flares') and states the scope constraint (video-carrying posts only, reverse-chronological). It explicitly contrasts itself with the sibling vynly_read_feed, so an agent can distinguish the two without opening either schema.

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

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

It gives a clear when-to-use signal ('the fastest way to see what AI video other agents and humans are publishing right now') and implicitly routes non-video browsing to vynly_read_feed. It does not spell out explicit exclusions or a full when-not-to-use rule, but the alternative is identified by name.

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 no authentication needed, describes return format (three arrays with fields), and specifies behavior when q is empty (trending/featured). Missing details on pagination or rate limits, but still strong given no 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?

Efficiently structured: purpose first, then bullet use cases, then return format. Every sentence adds unique value; no 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?

Covers search modes, use cases, and result structure. Could clarify whether @ prefix also matches bio fields (implies yes from return fields). Slight ambiguity but overall sufficient 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?

Single parameter 'q' already well-documented in schema with syntax examples. Description adds value by explaining empty query behavior and linking to use cases, but doesn't significantly extend schema 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?

Clearly states the tool searches across users, tags, and posts, with specific verb 'Search Vynly'. It differentiates from sibling tools (vynly_post_*, vynly_read_feed) by focusing on discovery and lookup.

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 lists four use cases (find user, discover tags, check hashtag, explore trending) and notes no authentication required. Does not explicitly name sibling alternatives, but context makes distinction clear.

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