sprkly-mcp

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?

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, and the description adds real-world consequence detail ('starts replying to real people right away') plus a validation constraint (coupon template refused until message holds the real code). It does not say what happens on a duplicate call or what the tool returns, but the safety-relevant behavior is well covered.

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

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

Front-loaded with the action and the user-visible warning, then the parameter rules; every sentence carries information. Slightly padded by the redundant restatement 'If it does not, leave post_id out,' which the preceding clause already implies.

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 setup, side effects, parameter conditions, a validation failure mode, and the off-switch, with no output schema to explain return values. The only gap is what an agent receives back (e.g., the created automation's id) for follow-up calls like pause/resume.

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 genuine conditional semantics beyond the schema: post_id only when asks_for has post and must be omitted otherwise, link must be a full https URL, keyword defaults to the template's word, and message replaces either the DM or the public reply on reply-only templates.

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 with scope ('Set up one ready-made automation on one Instagram account and turn it on') and maps it to a user-visible concept ('same as Go live in the app'). Clearly separable from siblings like sprkly_list_automation_templates, sprkly_import_automation_template, and sprkly_pause_automation.

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 prerequisites (show the user the template, account, word and link first), names the source tools for template_id and profile_id, and routes to sprkly_pause_automation for stopping. Conditional rules for post_id and link are spelled out rather than 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?

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?

Annotations declare the safe/non-destructive profile, but the description adds real behavior beyond them: the caption is truncated to the tightest limit among the target platforms, a draft id is returned, and the draft surfaces under /drafts for review. It omits that the call is non-idempotent (repeated calls create separate drafts) and says nothing about auth or limits.

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, zero filler, with the action and the most non-obvious behavior (tightest caption limit) front-loaded and the return/review consequence trailing. Every clause earns its place.

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

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

For a create tool with no output schema, the description covers the action, the shaping rule, and the return value (a draft id) and where the artifact lands. It stops short of stating any prerequisite account/profile context, which is a minor gap against a 5-param tool.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters and the enum values. The description adds only the conceptual framing that platforms drive the caption length ceiling, which the platform param description already states, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('compose a caption ... save it as a draft in sprkly') plus the scope of the computation ('shaped to the tightest caption limit among the target platforms'). It is distinguishable from sprkly_schedule_post by the draft-not-scheduled outcome, but it never names that sibling or any alternative explicitly.

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

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

Usage is only implied: 'save it as a draft ... for the user to review' suggests this is the pre-publication step before scheduling, but there is no explicit when-to-use statement, no condition that selects this over sprkly_schedule_post, and no prerequisites (e.g. whether a connected account or profile is 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 safety is partly covered. The description goes further and discloses the export's contents (trigger, keyword, message), the guarantee that no post id, profile id or account details are included, and the draft-automation failure case – useful context not present in the 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?

Three sentences, front-loaded with the action, each carrying distinct information (what is exported, what is excluded, and the draft/account constraints). No filler.

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

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

There is no output schema, but the description compensates by describing what the produced template file holds and what it deliberately excludes. Combined with the read-only annotation and the single required parameter, an agent has everything needed 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% and the single parameter is self-explanatory. The description implies the id refers to one Instagram auto reply but adds no syntax or format detail beyond the schema, matching the baseline for high-coverage schemas.

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+scope: 'Download one Instagram auto reply as a shareable template.' It is unambiguous and clearly distinguishable from siblings such as import_automation_template, list_automation_templates and create_automation_from_template, which move templates in the opposite direction.

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

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

Gives a precondition ('Needs a connected Instagram account') and an implied when-not case ('An auto reply that is still a draft has nothing published to export'), which tells the agent to expect failure for draft automations. It stops short of naming an alternative tool, so it is clear context rather than a full when/when-not/alternatives statement.

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

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

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?

Annotations only declare readOnlyHint=true and openWorldHint=false, so safety is covered, but the description adds substantial non-obvious behavior: Instagram contributes reach/saves/shares/views only for insights-permission accounts and likes/comments only for others; Threads and Facebook produce no metrics; `topPosts` ranking is per-platform and `relativeToPlatformBest` never crosses platforms. These are exactly the traits an agent would otherwise call wrong.

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?

It opens with what the tool returns and then layers interpretation rules, so it is front-loaded. It is long for a two-parameter read tool, but nearly every sentence carries a distinct interpretive constraint an agent needs to avoid misusing the numbers.

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?

There is no output schema, so the description carries the full burden of explaining returns and it names key fields (`samples`, `coverage`, `topPosts`, `relativeToPlatformBest`, `value`/`metric` label) plus platform caveats. It stops short of describing the full response shape, particularly the period-on-period structure, leaving a small gap.

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

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

Schema description coverage is 100%, so the schema already documents `days` (bounds, plan limits) and `profile_ids` (omit for all accounts). The description adds no additional parameter syntax or meaning, so the baseline 3 is 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 ('How the user's published posts actually performed') and enumerates the returned dimensions: views, engagement, week/month/year-on-year change, best posting hour/weekday/category, and top posts. This is clearly distinguishable from siblings like sprkly_get_account_summary and sprkly_get_post_status 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?

The description is dense with interpretation guidance (quote sample counts, read `coverage`, never rank platforms on a missing metric), but it never states when to choose this tool over an alternative such as sprkly_get_account_summary. Usage is implied rather than routed.

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 safety is covered; the description adds real behavioral value on top by defining the `ready` flag and its cause (Instagram has not yet granted messaging permission) and by scoping the counts to a monthly window with a stated reset. It stops short of describing throttling, auth requirements, or partial-failure behavior across accounts.

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 sentences with no filler; the core payload (what is counted, the limit, the reset) leads, and the `ready` caveat follows. The first sentence is dense but each clause carries distinct information, so nothing is wasted.

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

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

For a zero-parameter, read-only tool with no output schema, the description does the heavy lifting of describing the return shape (count, limit, reset, ready) and is therefore close to complete. Minor gaps remain around error/empty states (e.g. accounts with no automations) and whether results are paginated, but nothing essential to invoking 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter meaning is lost.

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 resource (automation usage) and enumerates exactly what is returned: per-Instagram-account message counts, the plan's monthly limit, and the reset date. This clearly separates it from sprkly_list_automations (which lists automations) and sprkly_get_billing_summary, though it never explicitly contrasts with those quota-adjacent siblings.

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

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

There is no explicit 'use this when...' statement or named alternative. The use case (checking messaging quota headroom before enabling an automation) is inferable from the enumerated return values, but the agent has to derive it — implied usage rather than stated 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 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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine domain behavior: messages are returned oldest-first, comment_id is embedded for replies, and dm_window encodes Instagram's 24-hour DM reply rule. That last point is real operational context an agent needs before attempting a reply.

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 resource and ordering, then two dense sentences of useful behavioral detail. No filler, though the dm_window rule is slightly tangential to the read operation itself.

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 takes on the burden of describing return content and does so well (DMs, comments, replies, automations, comment_id, dm_window). The one gap is that pagination or thread-size behavior is not mentioned, but the core contract is complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description discusses return artifacts (comment_id, dm_window) rather than adding format or syntax detail for profile_id, person_id, or handle, so it does not meaningfully extend 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 states a specific resource (one inbox conversation) and enumerates the contents returned (their DMs and comments, your replies, automations sent), which distinguishes it from sprkly_list_inbox_threads. The verb is only implied by the name/title ('get'/'Read'), but the scope is unmistakable.

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 states the prerequisite ('Needs inbox access') and points at sprkly_reply_to_comment as the consumer of comment_id, giving implied follow-up context. However, it never says explicitly when to call this vs. list_inbox_threads or when a thread should be retrieved.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower, yet the description still adds substantive behavior: the exact return contents (reviewer notes, requester, timestamps) and the non-obvious state transition where a rejected post reverts to a draft. No output schema exists, so this return-shape disclosure is genuinely load-bearing.

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 tight sentences with zero filler. The state enumeration is front-loaded, and the follow-up workflow note is appended only after the core answer, which is the right ordering.

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 single-parameter tool with no output schema, the description covers what comes back and the lifecycle semantics. The only unaddressed case is what is returned when no approval request has ever been made for the post, a minor gap.

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

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

There is a single required parameter, post_id, and schema description coverage is 100%, so the schema already carries the full burden. The description adds no syntax, format, or sourcing detail for post_id, which is the expected baseline when the schema is complete.

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 the resource (a post's approval) and enumerates the three states it reports (awaiting approval, approved, rejected), plus the ancillary data returned. That is far more specific than the title alone. It does not explicitly distinguish itself from the nearby sibling sprkly_get_post_status, which is the one ambiguity an agent could hit.

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

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

Usage is implied rather than stated: you call this to check approval state, and the second sentence gives a post-rejection workflow that points toward sprkly_request_post_approval. There is no explicit 'use this instead of X' or when-not-to-call guidance, and no statement of the prerequisite that an approval request must already exist.

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?

Far beyond the annotations, the description discloses what actually gets written, the draft-vs-live state transition, that certain account-wide DM templates are refused, and that a connected Instagram account is required. This is exactly the mutation/authorization/rate behavior an agent needs and annotations alone would not 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 two-mode behavior is front-loaded ('With no profile_id NOTHING is written'), and each subsequent sentence handles a distinct trigger case. It is dense but every sentence carries a rule; only slight tightening would help.

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 compensates by explaining that the check-only path hands the template back, and it covers the draft/live states and refusal case. For a nested-object, mutating tool, the coverage of behavior and prerequisites is complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine conditional meaning: it explains when post_id is required (single-post triggers) versus optional (keyword on any post, Profile DM), and clarifies profile_id as the write-enabling switch. It goes beyond restating the schema fields.

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

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

The description states a specific verb (import/read) and resource (auto reply template), and lays out the two modes (check-only vs create). It does not name or contrast with the nearby siblings sprkly_create_automation_from_template or sprkly_export_automation_template, so the agent must infer the distinction, but the operation itself is unambiguous.

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

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

It gives explicit conditional guidance: omitting profile_id is framed as 'the safe first call', and the post_id requirement is spelled out per trigger type. It stops short of naming alternative tools to reach for, but the when-to-use conditions are clear and actionable.

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 safety is covered; the description adds real value on top by disclosing the non-archived filter, the available states (On, Paused, Draft), and the non-obvious row-multiplication behavior (one row per account sharing a group_id). It doesn't discuss ordering, size limits, or empty-account behavior, which keeps it out of 5 territory.

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 dense sentences, front-loaded with the scope constraint ('not archived'), then the row shape, then the edge case that would otherwise confuse an agent. No filler or restatement of the title.

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 carries the burden of describing returns, and it does so field-by-field plus the group_id grouping rule. What's missing is minor: ordering, result-size expectations, and whether an empty result is indistinguishable from no automations.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4; there is no parameter semantics to document or misdocument. No corrective information is needed here.

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+resource ('Every Instagram automation on this account that is not archived') and enumerates the fields returned per row, so the agent knows exactly what this produces. It does not explicitly differentiate itself from the sibling list_automation_templates, which is the one plausible confusion point, so it stops short of a 5.

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

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

Usage is only implied: the agent can infer this is the way to enumerate existing (non-archived) automations, and the archived exclusion narrows the scope. There is no explicit when-to-use statement, no condition distinguishing it from list_automation_templates, and no mention of what to do next (get_automation_usage, pause_automation).

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 readOnlyHint=true already declaring the safety profile, the description adds real value by describing the shape of each returned item (id, name, goal, trigger, message) and the meaning of the asks_for field — information no annotation or output schema provides. It doesn't say whether results are account-scoped or paginated.

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 statement and useful examples, and the asks_for explanation earns its place. The trailing sentence 'Every plan has automations' is vague and slightly off-topic, costing it a point.

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

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

With no output schema, the description does the heavy lifting by describing returned fields and the asks_for handoff to the create tool, which is exactly what an agent needs. It's silent on result scoping (per-account/per-plan) and pagination, though the final sentence hints at plan-based availability without clarifying it.

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

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

The tool takes zero parameters, so the baseline is 4; there are no inputs whose semantics could be clarified. The description instead spends its words on the asks_for field of the returned objects, which belongs to results rather than inputs.

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?

Specific verb+resource, and it explicitly distinguishes itself from sibling sprkly_list_automations by calling these 'the ready-made Instagram automations, the same ones as the template gallery in the app.' It also enumerates the fields each result carries, so an agent knows exactly what this returns versus the create/list-automations tools.

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

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

It names the downstream tool, sprkly_create_automation_from_template, and explains that asks_for tells you what that tool needs beyond the template id and account — which implies the list-then-create workflow. It stops short of an explicit 'use this when you need a template id' statement or any 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?

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 and openWorldHint, so the safety profile is covered. The description adds real value beyond them: the return shape (one row per person per connected account with handle, unread count, last message) and the auth requirement (inbox access via a key or an allowed connection).

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

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

Front-loads purpose (recent conversations, newest first), then row shape, then usage, then auth. Each sentence earns its place, though the final access sentence is slightly dense. Overall well-sized for a 3-param list 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?

No output schema exists, yet the description compensates by describing the returned row contents, and it covers ordering, default filtering behavior, and the auth prerequisite. An agent has everything needed 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 coverage is 100%, so the baseline is 3, but the description adds meaning: unread_only is framed as 'conversations waiting for an answer' and profile_id is tied to the per-connected-account row concept. It goes beyond the terse schema 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 (list) and resource (inbox conversations/threads) with scope ('most recent... newest first') and describes the row shape. It names the sibling sprkly_get_inbox_thread and clarifies the relationship, so an agent can distinguish it from the read-one tool 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 clear usage context: pass unread_only to see conversations waiting for an answer, and use profile_id/person_id from a row with sprkly_get_inbox_thread to read a thread. This routes the agent to the right sibling. It lacks an explicit 'do not use when...' exclusion, so it falls just short of a 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?

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?

Goes beyond the annotations by disclosing two things they cannot express: the change applies to every account the automation runs on, and partial failures are surfaced by name in a 'failed' field. This is exactly the multi-account scope and partial-success behavior an agent needs before calling a cross-account mutation.

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, front-loaded with the core action and effect scope, with no filler. The trailing note about 'failed' is slightly terse and reads like a fragment, but it still carries useful 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?

For a single-parameter mutation with no output schema, the description covers the action, the blast radius, the reversibility path, and the partial-failure signal. Nothing material 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?

With one parameter at 100% schema description coverage, the schema already documents automation_id and even points to sprkly_list_automations as its source. The description adds no format, sourcing, or validation detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (stop/pause) and resource (an automation) plus the effect scope ('from replying, on every account it runs on'), which no sibling duplicates. An agent can distinguish it from sprkly_delete_scheduled_post or sprkly_resume_automation 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?

Names the counterpart tool explicitly ('sprkly_resume_automation turns it back on') and clarifies the non-destructive intent ('Nothing is deleted'), which gives clear context for choosing pause over deletion. It stops short of stating the conditions under which pausing is preferable, so it is strong context rather than a full when/when-not 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 flag it as a non-readOnly, open-world, non-idempotent write, and the description layers on rich context the annotations don't carry: the reply is publicly visible, irreversible ('cannot be taken back'), requires a user-confirmation step before sending, and needs inbox access. The retry caveat about unconfirmed sends is genuinely useful behavioral 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?

Front-loaded with the action and its public/irreversible nature, then practical workflow rules, then the precondition. Every sentence carries distinct operational value with no filler.

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

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

There is no output schema, and the description compensates by describing the observable outcome behavior ('if the answer says Instagram did not confirm...'), the visibility/reversibility profile, and the access requirement. An agent has everything it needs to call this correctly and handle the response.

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 both parameters (text length limit, comment_id source) are already documented in the schema. The description reinforces the comment_id source but adds no syntax or format detail beyond what the schema provides, 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?

States a specific verb and resource ('Post one public reply under an Instagram comment') plus the account scope ('from the account that got the comment'). This clearly separates it from sprkly_reply_to_dm, which handles private messages rather than public comment replies, without needing to open either schema.

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

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

Gives concrete when-to-use guidance: take comment_id from sprkly_get_inbox_thread, show the words to the user first, and a specific failure rule (if Instagram did not confirm, don't resend). It also states the prerequisite ('Needs inbox access'). It stops short of explicitly naming the alternative sibling (sprkly_reply_to_dm) and the condition that would select it instead.

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 mark it non-read-only, non-idempotent and open-world. The description adds substantial behavioral context beyond that: irreversibility ('cannot be taken back'), the 24-hour Instagram window, the side effect of pausing automations for 5 minutes, and explicit recovery guidance on an unconfirmed send.

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 tight sentences, each carrying distinct information (action, irreversibility, time window, side effect, failure handling, auth). Purpose is front-loaded and nothing is redundant.

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

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

No output schema exists, and the description compensates by explaining the failure-return case and the correct agent response. Combined with the auth and timing constraints, an agent has everything needed to invoke this 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% and all three parameters are documented there, including the 1000-character limit and the cross-reference to sprkly_list_inbox_threads. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (send/reply) and resource (one Instagram DM to a person who messaged this account, on behalf of the account owner). This clearly distinguishes it from the sibling sprkly_reply_to_comment, which targets a different surface.

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 concrete usage conditions: only within 24 hours of the person's last message, requires inbox access, and the human-in-the-loop step 'show the user the words first.' It also tells the agent what to do on an unconfirmed send. It stops short of explicitly naming alternative tools for other reply channels, so 4 rather than 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?

Annotations only supply the generic safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds substantial behavior on top: the exact state transition to pending_approval, that it never auto-publishes, the owner email side effect, the returned approval id, the approve/reject lifecycle (approved → scheduled, past-time → out in ~2 minutes; rejected → draft with notes), and the Power-plan restriction with upgrade_required.

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 core action and resulting state are front-loaded in the first sentence, followed by side effects, the sibling tool for polling, lifecycle outcomes, the alternative for new posts, and the plan gate. Every clause carries distinct, actionable information with no filler.

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

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

There is no output schema, and the description compensates by explaining what is returned (an approval id to poll) and the terminal states after approval or rejection. Combined with the plan gating and the new-post alternative, an agent has everything needed to call this 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 both parameters (post_id, note) are already documented in the schema. The description reinforces that post_id must be an existing draft or scheduled post and that note appears in the approval email, but adds no format, syntax, or constraint detail beyond the schema. 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 states a specific verb and resource ('Hold a draft or scheduled post for the owner's approval') and spells out the resulting state ('moves it to pending_approval'). It also distinguishes itself from siblings by naming sprkly_schedule_post (for new posts) and sprkly_get_post_approval_status (for polling), so an agent can route correctly 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?

Explicit when-to-use ('hold a draft or scheduled post'), when-not and the alternative ('To hold a NEW post, pass requires_approval to sprkly_schedule_post instead'), plus the plan gate that blocks other plans. The repeated-call case is also addressed ('Asking again for a post that is already waiting returns the same request').

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 cover the safety profile (readOnly=false, idempotent=true, non-destructive), so the description correctly spends its words elsewhere: cross-account scope, the real-world side effect of replying to people again, and the preconditions/exclusions that would make the call a no-op or invalid. It stops short of describing what happens on failure or how the resumed state is confirmed.

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, front-loaded with the action, and each sentence carries distinct information (effect, scope, precondition, exclusion). Slightly colloquial phrasing ('replying to real people again') makes the last clause feel oblique, but there is no filler.

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

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

For a single-parameter mutation with annotations already declaring idempotency and non-destructiveness, and no output schema, the description supplies everything an agent needs: scope, side effect, precondition, and the case where the call will not take effect.

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

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

Schema description coverage is 100% for the sole parameter, and the description adds nothing about automation_id beyond what the schema already states (the value comes from sprkly_list_automations). The implicit point that no account parameter is needed because resume applies to all accounts is mild added meaning; 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?

A specific verb plus resource — turn a paused automation back on — that an agent can distinguish from the sibling sprkly_pause_automation without opening either schema. It also states the operational scope ('on every account it runs on'), which clarifies what 'resume' actually affects.

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

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

Gives a precondition ('A draft has to be finished in sprkly first') and an explicit exclusion ('An automation that hit its "stop after this many people" limit stays off'), which is real when-to-use guidance. It does not, however, name the sibling tool it pairs with or the inverse operation (sprkly_pause_automation), so routing is implied rather than stated.

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

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

Annotations only declare the safety profile (non-read-only, open-world, non-idempotent). The description adds the real behavioral traits: it runs the same quota/duplicate/platform pre-flight checks as the app, it downloads media into storage itself, Instagram/TikTok media and YouTube/TikTok title constraints, and the needsAccountChoice return path. This is rich context 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?

Dense but front-loaded and ordered: purpose, media guidance, pre-flight/requirements, return-value relay, confirm-with-user, account-choice fallback. Nearly every sentence carries a distinct instruction; it is somewhat long, but no sentence is filler.

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

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

For a 14-parameter tool with nested objects and no output schema, the description covers what is needed: platform requirements, required privacyLevel, response-relay expectations, the account-choice branch, and approval semantics. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% so baseline is 3, but the description goes further by framing the media_urls vs media_ids tradeoff ('fewer steps' for a link just given), naming the privacyLevel requirement and that the tool echoes allowed values, and clarifying account-fanning behavior. It adds selection meaning beyond the schema's per-field text.

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 ('Queue a post for publishing') and immediately differentiates from siblings: it emphasizes ONE call and that no upload tool (sprkly_upload_media / sprkly_add_media_from_url) needs to run first, and the draft-vs-schedule distinction from sprkly_draft_post is implicit in 'for publishing'.

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 guidance and alternatives: pass the link to media_urls vs using pre-uploaded media_ids, use profile_ids when the user has media in sprkly, confirm date/time/accounts with the user first, and handle needsAccountChoice by putting the choice to the user then re-calling. Routing conditions are spelled out, not inferred.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior beyond that: the status is invariant across edits, approval is not granted as a side effect, a rejected post remains a draft, and a pending-approval post may only target one account. It omits side effects such as whether edits re-trigger notifications or reset approvals.

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, front-loaded with the editable surface and followed by the status constraints. No filler, and the most decision-relevant constraint (status never changes) is stated early.

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 6-parameter mutation tool with no output schema and annotations that already carry the safety profile, the description covers eligibility, field scope and key invariants well. What an agent gets back after a successful edit is left entirely implicit, though no output schema exists to offset that.

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 baseline is 3 and the schema already documents every field, including the replace-not-append semantics of media_ids. The description adds meaning on top: the one-account ceiling for posts awaiting approval constrains profile_ids in a way no schema field states.

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

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

The description states a specific verb (change) plus the resource (a post that has not published yet) and enumerates the editable fields: caption, publish time, target accounts, attached media. It also pins the eligible statuses (scheduled, pending_approval, draft), which separates it cleanly from sprkly_schedule_post, sprkly_delete_scheduled_post and sprkly_request_post_approval.

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 clear eligibility conditions and explicitly distinguishes the edit path from the approval path ('editing a post that waits for approval does not approve it'), which is real routing guidance. It never names a sibling tool directly and gives no explicit when-not-to-use beyond the 'not published yet' gate, so it stops short of 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?

Beyond the idempotentHint annotation, the description adds rich behavioral context: presigned upload URLs, 15-minute link expiry, 50 MB and 35-file limits, the PUT flow, and that identical bytes yield the same media_id. It also explains that bytes never pass through the agent, which is valuable for cost and architecture understanding.

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 section earns its place: mode selection, limits, workflow, and exclusion criteria. It is front-loaded with the core purpose, though a bit dense; minor tightening could make it even easier to scan.

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 no output schema, the description fully covers what an agent needs: how to get upload URLs, how to upload bytes, what the response contains, limits, idempotency, and which sibling to use for public links. 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?

Although the schema already covers all parameters, the description adds meaning beyond it: it distinguishes the two modes, clarifies that files takes precedence over inline params, explains when data_base64 is appropriate, and provides concrete bash commands for computing sha256 and size_bytes.

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: upload local files into sprkly and receive a media_id per file. It clearly distinguishes this from URL-based or public-link workflows, including naming the schedule_post alternative for public links.

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 explains when to use LINK MODE versus INLINE MODE, including file size thresholds, and directs users to sprkly_schedule_post for public links. This gives an agent actionable routing guidance beyond just naming the tool.

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

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

Annotations already declare readOnlyHint=true, so 'Pure analysis. Writes nothing.' reinforces rather than reveals. The real added value is the enumeration of what is actually checked (length, media requirements, hashtag ceilings, link clickability, YouTube titles, PII/prohibited content), which goes well beyond the annotation surface; missing are error behavior or whether results are per-platform verdicts.

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, front-loaded with the concrete list of checks and closed by the read-only guarantee. Every clause carries information; no filler or repetition of the tool name.

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

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

With no output schema, the description does important work by naming the checks, which implies what the result covers, and it resolves the ambiguity of a nested platformMeta object by scoping the tool to a caption-level check. It could go further by indicating whether results are returned per platform with pass/fail detail.

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%, with title, mediaUrlsCount, hashtags and platforms all documented in the schema itself. The description's mentions of YouTube titles and media requirements map directly onto those existing schema descriptions, adding little beyond them; the nested platformMeta object remains unexplained in either place.

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 ('Check') and resource (a caption against each target platform's posting rules) and enumerates the exact rule categories checked. It is clearly distinguishable from the write-oriented siblings like sprkly_schedule_post or sprkly_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?

'before scheduling' gives a clear usage moment, and the scope ('each target platform') tells the agent this is a pre-flight check rather than a one-shot lint. However, it never explicitly names alternatives (e.g., use schedule_post once validation passes) or states when not to use it, so it stops 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.