sprkly

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

Beyond the annotations, the description discloses meaningful behavioral details: files are downloaded into storage, Google Drive and Dropbox share links are converted automatically, the file must be publicly shared, and there is a 50 MB limit. These are useful execution traits not expressed in the structured metadata.

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

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

The description is compact and well-structured: it opens with the primary action and output, then provides a clear when-not-to-use note, then adds the key constraints. Every sentence carries useful information without redundancy.

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

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

For a single-parameter tool, the description is complete: it explains the returned media_id, the reuse purpose, the relationship to schedule_post, supported link conversion, public-access requirement, and size limit. Even with no output schema, the agent knows what to expect.

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

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

The schema already documents the url parameter well, including that it must be a direct https link and publicly reachable. The description adds extra semantic context—conversion of Google Drive/Dropbox share links and the 50 MB size restriction—which helps the agent choose appropriate input values.

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

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

The description states a specific action—'Download an image or video from a public link into sprkly and get a media_id back'—and clearly distinguishes it from the sibling sprkly_schedule_post, which accepts media URLs directly. This makes the tool's unique role 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?

The description explicitly states when the tool is not needed ('You usually do NOT need this'), identifies the alternative tool, and gives the exact condition for using this tool: when the user needs one media_id reused across more than one post. This is exemplary usage 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?

Beyond the annotations (destructiveHint: true), the description reveals critical behavioral traits: this is a soft delete with a 30-day recovery window, restorable from the Deleted tab. This tells the agent the action is reversible and explains the irreversible boundary ('Posts that have already published cannot be deleted this way'). The confirmation requirement is an additional behavioral context that no annotation captures.

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?

Five concise sentences, each adding distinct value: purpose, delete type, recovery detail, limitation, and safety instruction. The text is front-loaded with the core action and contains zero fluff or redundant restatement of the title or annotations. Perfectly sized 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?

For a simple tool with 1 parameter, no output schema, and rich metadata annotations, the description is complete: it covers the purpose, soft-delete behavior, recovery period, edge-case limitation (published posts), and safety requirement. Without an output schema specified, the description need not explain return values. 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?

With schema description coverage at 100% (the single post_id parameter is fully documented in the schema) and only 1 parameter, the description doesn't need to add much parameter-level detail. The description does not elaborate on the id format or how to obtain it, but does reinforce the parameter's meaning by referencing 'a post' being removed from the queue. Baseline of 3 is appropriate since the schema already handles 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 opens with 'Remove a post from the queue', a direct verb+resource statement that clearly conveys the tool's purpose. The title 'Delete a scheduled post' and the description together unambiguously distinguish this from sibling tools like 'sprkly_update_scheduled_post' and 'sprkly_draft_post', leaving no ambiguity about what this 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?

The description provides explicit usage guidance: it states when to use this tool ('Remove a post from the queue') and when not to ('Posts that have already published cannot be deleted this way'). Crucially, it includes a mandatory human-safety guardrail: 'Always confirm with the user before calling.' These exclusions and instructions go well beyond a generic usage note, offering clear when-to and when-not-to 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 the main side effect (saving a draft), the return value (draft id), and the visible result (draft appears under /drafts). It adds useful behavioral detail about caption length limits, and 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?

Two concise sentences lead with the verb and key purpose, then specify return and review location. Every sentence earns its place and there is no redundant 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 no-output-schema tool, the description explains the return value, the side effect, and the draft's visibility to users. It could mention limitations or how drafts relate to scheduling, but is otherwise 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?

Schema description coverage is 100%, so all five parameters are already documented. The description adds little that is not in the schema; its mention of 'tightest caption limit among the target platforms' merely paraphrases the platform parameter's schema description.

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 action: compose a caption from a content hint and save it as a draft in Sprkly. It names the resource ('draft'), explains how platforms affect the caption, and distinguishes this from sibling tools like scheduling or approving 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?

The usage context is implied: the draft is saved 'for the user to review', which suggests pre-publishing workflow. However, it does not explicitly state when to use this tool instead of sprkly_schedule_post, sprkly_request_post_approval, or other siblings.

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 the description adds a meaningful behavioral guarantee: 'Never returns tokens or secrets.' This security-related disclosure goes beyond the annotations and is valuable for safe invocation, though it does not cover other potential behaviors like caching or data freshness.

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, information-dense sentence that front-loads the returned data elements and ends with a security note. Every word contributes value, with no repetition or filler.

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

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

Given there is no output schema, the description carries the full burden of explaining what the tool returns. It covers the main data categories sufficiently for a summary tool, though it omits details like exact field names or status values. Overall, it is adequate for the tool's simplicity.

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 has zero parameters, so the baseline for this dimension is 4. The description correctly avoids mentioning parameters, and nothing more 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?

The description clearly enumerates what the tool returns: plan tier, trial state, connected account count, scheduled post counts by status, and next three upcoming posts. This makes the resource and scope unambiguous and distinguishes it from siblings like sprkly_get_billing_summary and sprkly_get_analytics.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or sibling tools for comparison, leaving the agent to infer usage context from the data content alone.

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 `readOnlyHint: true` annotation, the description discloses nuanced behavior: recommendations carry sample counts, percentages include base totals, `topPosts` is ranked only within platform groups, and platform metric coverage varies (Instagram likes/comments only; Threads/Facebook no metrics). This is exactly the kind of contextual behavior an agent needs and goes well 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?

The description is dense but all sentences carry substantive caveats. It is somewhat run-on and would benefit from bulleted structure, but the front-loaded purpose sentence and focused details keep it usable.

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

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

With no output schema, the description does the heavy lifting: it names the key result fields (`samples`, `topPosts`, `relativeToPlatformBest`, `coverage`, `value`, `metric`) and explains grouping/ranking and comparability constraints. This is sufficient for an agent to know what to expect and how to interpret results.

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%, so the schema already describes `days` and `profile_ids` adequately. The description does not add new parameter-level semantics such as defaults or interaction effects, so it earns the baseline 3.

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-plus-resource statement: "How the user's published posts actually performed" followed by a concrete list of outputs (total views, engagement, period-over-period changes, best posting hour, weekday, category, top posts). This clearly distinguishes it from sibling tools like get_account_summary or get_post_status.

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

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

The description provides clear context for when the tool is useful and how to interpret it, e.g., quoting `samples` for thin evidence and reading `coverage` before comparing platforms. It does not explicitly name alternatives or when-not-to-use conditions, but the scope ('published posts') implies appropriate use.

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

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

Beyond the readOnlyHint annotation, the description adds transparency by disclosing that payment method details are omitted and that the Stripe customer ID is truncated, which are important limitations an agent should know. This enhances understanding of what the tool returns and does not return.

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, tightly packed sentence that clearly lists contents and exclusions. It is front-loaded with the primary content and has zero wasted words, making it highly efficient.

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

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

For a read-only summary tool with no parameters and no output schema, the description provides a comprehensive overview of what will be returned (subscription status, plan, period end, purchased handles, billing events) and what will not (payment details, full Stripe ID). This is sufficient for the agent to know what to expect.

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 baseline is 4. The description correctly does not need to explain parameters, and the schema already confirms no inputs. No additional parameter information is necessary.

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

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

The description clearly states the tool retrieves billing summary information, listing specific components (subscription status, plan, period end, purchased handles, billing events) and explicitly notes what is excluded (payment method details, truncated Stripe ID). This distinguishes it from sibling tools like get_account_summary and get_analytics by focusing on billing specifics.

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 billing-related information is needed, but it does not explicitly state when to use it versus alternatives or provide exclusions. It lacks guidance on when not to use this tool, such as when full payment details are required.

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 openWorldHint: false, so behavioral safety is covered. The description adds value by specifying the returned data (reviewer notes and timestamps), which is beyond annotation coverage and provides useful behavioral context.

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, clear sentence that immediately states the purpose and what is included. It is concise, front-loaded, and contains no extraneous 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?

Given the tool's simplicity (one required parameter), existing annotations, and lack of an output schema, the description is sufficient. It explains the output scope (approval state, reviewer notes, timestamps) and does not leave major gaps. Minor edge-case details (e.g., errors or missing posts) are not necessary for this level of complexity.

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% for the single property post_id, which is already well-documented ('The scheduled post id.'). The description does not add any additional meaning about the parameter beyond the schema, so a 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 tool's purpose: it retrieves the approval status of a post (awaiting review, approved, or rejected) and includes reviewer notes and timestamps. This is a specific verb (get) with a specific resource (approval status) and differentiates from sibling tool sprkly_get_post_status, which likely covers general posting status.

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

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

The description implies when to use it (when you need approval status and related details) but does not explicitly exclude alternatives or mention when not to use it. Given the clear name and context, the usage is easily inferred, but there is no explicit guidance on alternatives like sprkly_get_post_status.

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?

ReadOnlyHint is already true, but the description adds valuable behavioral detail: media comes back as mediaIds, not links, and failure reason is included if not published. It also advises not to read ids out loud—beyond the annotation's scope.

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, tightly packed with all necessary details. The first sentence states what data comes back; the second adds crucial format and interaction notes. 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?

With no output schema, the description covers the return values explicitly (status, targets, times, permalink, failure reason, mediaIds). It also handles potential edge cases (e.g., failed publication). The id handling guidance further completes the context for real 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 coverage is 100% for post_id, so baseline is 3. The description adds extra context about how to handle ids (plumbing, talk by caption/handle), which goes beyond the schema's simple 'The scheduled post id' and informs the parameter's usage in conversation.

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 retrieves full detail for one post, listing specific fields (status, targets, times, permalink, failure reason). This distinguishes it from sibling tools like sprkly_list_scheduled_posts (which lists) and sprkly_get_post_approval_status (which is approval-specific).

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 clearly implies usage for retrieving details of a single specific post, as opposed to listing or approval. There's no explicit 'when not to use', but the context is clear. It also provides guidance on how to interact with ids, which is useful.

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 the description adds that data is fetched live and that schedule_post will check it itself. This adds useful context 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?

Two concise sentences cover purpose and usage, with no redundancy or 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 readOnly annotation and simple parameter, the description is complete: it explains the purpose, when to use it, and clarifies that scheduling does not require it. Nothing essential is missing.

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

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

The schema already fully describes the single parameter profile_id. The description repeats this information but adds no additional nuance beyond referencing sprkly_list_profiles as the source.

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 fetches allowed TikTok privacy levels and interaction settings, distinguishing it from sibling tools like scheduling or listing.

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 says when to use (user asks for options or offering a choice) and when not (usually not needed for scheduling, as schedule_post handles it). This is actionable guidance.

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

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

Annotations already specify readOnlyHint=true, which is consistent with the description's non-mutating nature. The description adds valuable behavioral context beyond annotations: it filters out disconnected/inactive accounts (so only valid posting targets are returned) and explicitly states that access tokens are never returned, addressing security expectations. This is more than many read-only tools 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 two sentences, directly stating the core function and key constraints. It is front-loaded with the most important information (what accounts are returned) and adds a crucial note about profileId validity. Every word serves a purpose, with no filler or redundancy.

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

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

Given the tool's simplicity (no parameters, no output schema), the description fully covers what an agent needs to know: the exact fields returned, the filtering behavior, the guarantee that returned IDs are valid posting targets, and the absence of access tokens. It is complete for a tool of this complexity, especially with readOnlyHint already declared.

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 schema coverage is trivially 100%. According to the rubric, a baseline of 4 applies when there are no parameters. The description adds no parameter-specific information because none exist, but it effectively communicates the tool's fixed behavior.

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

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

The description clearly states the tool's purpose: listing every ACTIVE social account linked to the sprkly account. It specifies the fields returned (platform, handle, follower count, reconnection status) and distinguishes itself from siblings like sprkly_list_profiles by emphasizing that only active, connected accounts are included and that profileId values are valid posting targets.

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 when to use this tool: when you need a list of active, connected social accounts for posting or management. It notes that disconnected/inactive accounts are never listed, which helps prevent misuse, but it does not explicitly name alternative tools or state when not to use it. Still, the context is clear enough for an agent to infer appropriate usage.

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 openWorldHint=false. The description adds useful context by specifying that the tool returns profile IDs, platforms, and handles needed for targeting. It does not contradict annotations and provides meaningful behavioral detail beyond the structured metadata.

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 succinct sentences: the first defines the tool's output, and the second gives a clear usage directive. Every word contributes to understanding, with no redundancy or filler.

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

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

Given the tool's simplicity (zero parameters, read-only, no output schema), the description adequately covers its purpose, returned content, and usage timing. It could be slightly richer by explicitly stating that it returns a list of all available posting targets, but it is complete enough for effective tool selection and 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, and the input schema is an empty object with 100% coverage. There are no parameter semantics to explain. The baseline for zero-parameter tools is 4, and the description adds relevant context about the returned data instead.

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 lists posting targets, specifically the profile IDs needed to target a post, along with each platform and handle. The title 'List posting targets' aligns with the description and distinguishes it from sibling tools like sprkly_list_connected_social_accounts by focusing on post targeting.

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 an explicit usage instruction: 'Call this before sprkly_schedule_post.' This gives clear context on when to use the tool. However, it does not mention when not to use it or name alternative sibling tools, so it stops short of full exclusions.

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

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

The description adds valuable behavioral details beyond the readOnlyHint annotation: it specifies sorting (newest first), returned fields, support for a status filter, and cursor pagination. This gives the agent a clear picture of the tool's 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?

The description is brief and front-loaded, with two sentences that efficiently convey the core purpose and key features. Every word 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?

Given the tool's simplicity (3 optional params, no output schema) and the readOnly annotation, the description covers all essential aspects: what is returned, sorting, filtering, and pagination. It is complete for an agent to use 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?

With 100% schema description coverage, the baseline is 3. The description mentions 'status filter' and 'cursor pagination' but these are already captured in the schema parameter descriptions. No significant extra meaning is added beyond the structured 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 what the tool does: it lists the post queue (scheduled posts) sorted newest first, with specific fields like caption preview, targets, status, and failure reason. This distinguishes it from sibling tools like sprkly_get_post_status (single post) and sprkly_list_profiles (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 description provides clear context that this tool shows the post queue, implying use for viewing scheduled posts. However, it does not explicitly mention when not to use it or suggest alternatives, so it falls short of a 5 but is still informative.

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 convey non-read-only, non-idempotent, non-destructive behavior, and the description adds meaningful workflow context: it moves the post to pending_approval and returns an approval id to poll. This clarifies the state change 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?

Three concise sentences with no filler. The first sentence states the core action, the second describes the state change and return value, and the third gives usage guidance. 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 simple two-parameter mutation tool with no output schema, the description covers the action, state transition, return value, and polling mechanism. It is complete enough for an agent to invoke it correctly, though it does not mention edge cases like what happens if the post is not in draft state.

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 parameters are already fully documented. The description adds the workflow context that post_id refers to a draft post and that polling via sprkly_get_post_approval_status is expected, but it does not add significant semantic 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?

The description uses a specific verb ('Submit') and resource ('draft post') and clearly distinguishes this tool from siblings by naming the pending_approval workflow. It also states the result (approval id) and the polling companion tool, leaving no ambiguity about its 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 explicitly says 'Use this when the user wants a person to sign off before anything publishes,' giving clear context for selecting this tool. It does not explicitly name alternatives or when-not-to-use scenarios, but the sibling names and this sentence sufficiently orient the agent.

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

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

The description goes beyond annotations by detailing behaviors: it runs pre-flight checks, downloads media automatically, enforces shape constraints (same shape for multiple images), imposes platform-specific requirements (title needed for YouTube/TikTok), and explicitly handles ambiguous account selection. This is more than what the schema or annotations disclose. No contradiction with annotations; readOnlyHint=false is consistent with scheduling actions.

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 every segment serves a purpose—media handling, platform constraints, confirmation steps, and pre-flight checks. It is front-loaded with the main action and then systematically covers parameter details. No redundant or filler sentences, though its density might be intimidating; it earns a high score for relevance.

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 11 parametersBarnaby no output schema and significant platform-specific behavior, the description covers all necessary context: prerequisites, failure modes (refusals, needsAccountChoice), default behaviors, and cross-tool references. It is exhaustive and leaves no critical ambiguity for an agent to resolve.

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% but the description enriches each parameter significantly: it explains when to use media_urls vs media_id (fewer steps for links, no prior upload), the default scheduling behavior (immediate if omitted, no smart timing), the meaning of all_accounts as an explicit opt-in, and the nested platform_meta fields and their constraints. This goes well beyond the schema's basic attribute names.

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: 'Queue a post for publishing, in ONE call.' It explains what the tool does (schedules a post, runs pre-flight checks), and differentiates from siblings like sprkly_update_scheduled_post and sprkly_add_media_from_url by emphasizing that media URLs are handled inline, avoiding a separate upload step. This makes it unambiguous when to use this tool versus others.

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 usage guidance: when to use media_urls vs media_ids, the requirement for Instagram/TikTok media at submission time, the need to confirm with the user when there are multiple connected accounts, and the exact scenario (needsAccountChoice) to re-call. It also references alternative tools (sprkly_get_tiktok_posting_options) contextually. These are clear, actionable conditions.

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

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

Annotations already indicate readOnlyHint=false (mutation) and destructiveHint=false, so the description doesn't need to repeat that. It adds the constraint that only scheduled posts can be edited, which is useful context beyond annotations. It doesn't describe side effects like media replacement behavior or confirmation, but that's minor given 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 sentences with no wasted words. The first sentence states the action and scope, the second adds a critical constraint. Front-loaded with the core 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?

For a tool with 6 parameters and no output schema, the description is sufficiently clear for an agent to invoke correctly. It covers the essential constraint (scheduled posts only) and the editable fields. It doesn't explain edge cases like time validation or media replacement, but these are covered by schema parameter descriptions and reasonable assumptions.

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 parameters are documented. The description lists the editable aspects (caption, time, accounts, media) but doesn't add meaning beyond what the schema already provides. It doesn't explain partial update behavior (only required post_id), but that's implicit 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 function: changing caption, publish time, target accounts, or media on an existing scheduled post. It distinguishes from siblings like sprkly_schedule_post (creating) and sprkly_delete_scheduled_post (deleting) by specifying it edits existing scheduled 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?

It provides a key usage constraint: only posts with status 'scheduled' can be edited, which tells the agent when not to use it. However, it doesn't explicitly mention alternatives like creating a new post with schedule_post for unscheduled content, though the constraint implies that.

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 the description reinforces with 'Pure analysis. Writes nothing.' It also exposes behavioral details beyond annotations, such as checking for 'PII or prohibited-content warnings' and 'whether links are clickable.' This adds value and 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 and front-loaded: it starts with the main verb 'Check' and lists checks in a readable comma-separated sequence. It ends with two short sentences ('Pure analysis. Writes nothing.') that reinforce safety. No redundant wording or filler; 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?

The tool has 6 params (2 required) and no output schema. The description explains what it checks, but not the exact return format (e.g., a list of issues, a boolean, or a report). Given the complexity and the absence of an output schema, describing the return type would improve completeness. Still, the purpose and scope are well-covered, and annotations provide safety context, so it is fairly complete but not perfect.

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 each parameter is already documented. The description references some parameters (e.g., 'required YouTube titles' for title, 'media requirements' for mediaUrlsCount, 'hashtag ceilings' for hashtags) but does not add new syntax or format details beyond the schema. It provides contextual mapping but not additional semantic depth, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'Check a caption against each target platform's posting rules before scheduling.' It lists specific checks (caption length, media requirements, hashtag ceilings, clickable links, YouTube titles, PII/prohibited content) and explicitly distinguishes it as 'Pure analysis. Writes nothing.' This differentiates it from mutation tools like schedule_post or draft_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?

The description gives clear context: 'before scheduling' indicates when to use this tool, implying it is a pre-flight check. However, it does not explicitly name alternatives or state when not to use it. It could be improved by mentioning 'Use this before scheduling; if issues are found, address them before calling schedule_post.' Still, the timing guidance is useful.

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