Taplio for LinkedIn

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

Annotations only declare the mutation/idempotency profile; the description adds substantive behavior: the server downloads and stores the file, and on an unreachable or non-public url the draft is silently left text-only rather than erroring. That failure-mode disclosure is exactly the kind of context annotations cannot carry. It omits whether attaching replaces or adds alongside existing draft media, and does not address idempotencyHint=false.

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

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

Front-loaded with purpose, then mechanism, then usage and fallback. The em-dash clarification about the url is long but earns its place; the final clause about the composer is slightly padded but still informative. No filler sentences.

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

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

For a 3-parameter mutation with an output schema and full annotation coverage, the description supplies the missing pieces: what the server does with the url, and what happens on failure. Only the interaction with pre-existing draft media is left unaddressed.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds a genuinely non-obvious clarification: 'url is the location of a media file the server downloads and stores, not an API endpoint the caller constructs.' That preempts a plausible misuse given the existence of create_media_upload_url. It also implies the public-https constraint that the schema only states flatly.

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 ('Attach an image or video to a LinkedIn post draft') plus the mechanism ('by giving a public https url'), which separates it from upload_media or pick_media in substance. It never names those siblings directly, so an agent must infer the distinction rather than being told.

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 situational cue ('before scheduling or publishing', 'to illustrate a draft you created or edited') and a fallback (use the Taplio composer). It does not state when to prefer this over upload_media, create_media_upload_url, or pick_media, which are the real choice points given the sibling list.

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 destructive/idempotent/not-read-only, yet the description adds real behavioral context: the exact effect ('never reaches LinkedIn'), the refusal condition, the error code comment_not_cancellable, and explicit guidance not to retry. That is disclosure well beyond the annotation set.

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 front-loaded sentences: purpose, then return shape, then error semantics. No filler; each sentence carries distinct, load-bearing 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 one-parameter mutation with annotations and an output schema, this covers purpose, side effects, return shape, and terminal error handling with user-facing guidance. Nothing needed to invoke or interpret 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% and the single parameter is fully described there ('The id of the committed comment draft to cancel'). The description reinforces the 'committed' state requirement but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource with scope: 'Cancel a committed comment before it is sent, so it never reaches LinkedIn.' The state qualifier ('committed') implicitly separates it from draft-creation/delete siblings, but no sibling is named, so it stops short of a clean 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?

Clearly conveys when to use it (a committed comment not yet sent) and what happens in every failure state ('never committed, is posted, failed or cancelled, or is being sent is refused'). It even tells the agent to stop retrying, but it never names an alternative tool (e.g., delete_draft) for the non-committed case.

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 well beyond the annotations by disclosing the return shape (status cancelled plus failure_reason) and the exact error codes connection_not_cancellable and connection_not_found, including what each means and how the agent should respond. The annotations already cover mutation/destructive/idempotent traits, and the description adds rich behavioral context on top.

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 action and scope, followed by return behavior and failure modes. Every sentence adds actionable information with no repetition.

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?

Complete for a one-parameter mutation tool with an output schema: the description covers scope, return status, error semantics, and retry guidance, while annotations and schema handle safety and input details.

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

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

Schema coverage is 100%, and the single username parameter is already documented as the recipient's LinkedIn public username matching send_connection_request. The description references username only indirectly through error cases, so it adds little parameter meaning 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?

States a precise verb and resource ('Cancel a connection request') and adds the critical scope ('before it is sent, so the invitation never reaches LinkedIn'). This clearly distinguishes it from send_connection_request and get_connection_request without needing the schema.

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

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

Explicitly defines the valid window (before sending) and enumerates the states where cancellation is refused, with a clear instruction not to retry. It does not, however, name an alternative tool for inspecting or handling already-sent requests, so it stops short of full when-to-use-vs-alternatives 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 flag destructiveHint and idempotency, but the description adds the state machine it operates over (sent, failed, cancelled, in-flight), the refusal code like_not_cancellable with a reason, and the not-found case like_not_found. That is real behavioral context beyond structured fields.

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

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

Three tight sentences with no filler; the primary action and its guarantee are front-loaded, followed by the two failure modes in a logical order.

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

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

For a one-parameter cancellation tool with annotations present and an output schema covering return shape, the description supplies everything an agent needs: success semantics, refusal semantics, and the recommended user-facing response on failure.

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 post_urn parameter is documented there as the value returned by like_post. 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 and resource ('Cancel a like before it is sent') with an explicit scope constraint ('so it never reaches LinkedIn'), which cleanly separates it from the sibling like_post that creates likes. Nothing about the intent is ambiguous.

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 conditions under which the call succeeds versus fails, and prescribes the right agent behavior on failure ('tell the user it can no longer be cancelled rather than retrying'). It stops short of naming a sibling alternative for creating/cancelling other like states, so it is strong context without explicit alternative routing.

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 well beyond the annotations (destructive, non-idempotent, open-world) by explaining that the call only queues the comment, that it returns status pending with scheduled_for, that posting can be delayed by posting windows or hourly limits, and that delivery is irreversible once live. It also documents the comment_commit_blocked / COMMENT_ALREADY_POSTED failure paths, which no annotation could convey. Nothing here contradicts destructiveHint=true or idempotentHint=false; it reinforces both.

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 crucial 'this only schedules, it is NOT live' correction, then layered with follow-up, cancellation, retry, and error semantics. It is dense and long, but each sentence carries distinct operational information; the error-code sentences in the tail could be tightened.

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 everything an agent needs despite an output schema being present: the queued semantics, the fields to quote back (scheduled_for), the follow-up verification path, the irreversibility boundary, retry safety, and the duplicate-comment rejection codes. Complete for a non-idempotent, destructive, open-world mutation.

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

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

Schema coverage is 100% and the single parameter is already documented, so the baseline is 3. The description adds only mild value by framing the id as a draft to be scheduled rather than an already-posted comment, but the bulk of parameter meaning is still carried by the schema.

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

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

States a specific verb and resource (commit a comment draft) and immediately clarifies the actual effect: it schedules a comment to be posted on LinkedIn under the user's name on someone else's post. That distinguishes it from the neighboring draft/schedule/publish siblings without the agent needing to open any schema.

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

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

Explicitly names the follow-up and alternative tools and the conditions that select them: get_comment_draft to confirm the outcome, cancel_comment_draft to stop it before sending, and the fact that it is unsafe to retry because a re-commit is rejected. When-to-use and when-not-to-act guidance is fully covered.

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

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

Annotations only say readOnlyHint=false / destructiveHint=false, which is ambiguous for a tool that talks to an external network. The description resolves that by stating nothing reaches LinkedIn until commit, and it discloses the uniqueness constraint, the refusal error (comment_commit_blocked / COMMENT_ALREADY_POSTED), and the required non-retry behavior — none of which appear in annotations or schema.

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

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

Four sentences, each doing distinct work: what it drafts, that it is unpublished, where the URNs come from, and the refusal/do-not-retry rule. The unpublished-and-review instruction is front-loaded ahead of the edge cases.

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

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

With an output schema present, return values need no explanation; the description instead covers the workflow, the source of each parameter value, the uniqueness rule, and the error path. Nothing an agent needs to invoke this correctly or handle failure is missing.

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

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

Schema description coverage is 100% and the schema already explains content length, post_urn provenance, and that comment_id turns the draft into a reply. The description restates that post_urn and the reply target come from the finder tools, adding provenance context but no syntax or format detail beyond the schema, 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 ('Draft a LinkedIn comment ... or a reply to a comment on it') and immediately frames the artifact as unpublished, which separates it from commit_comment_draft and update_comment_draft. An agent can identify the tool and its output without opening the schema.

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

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

Gives the full workflow: write the text here, show the user, then call commit_comment_draft only on agreement. It also names the prerequisite lookup tools (find_posts_to_comment, find_comments_to_reply), the one-comment/one-reply constraint, the exact failure code, and an explicit 'Do not retry' instruction.

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 this is a non-read-only, non-destructive, non-idempotent write, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the record is created in an unpublished state, media must already be uploaded before its id is usable, and the draft requires a separate publish/schedule step to become live.

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

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

Three short sentences with the core create action front-loaded, followed by the media attachment mechanics and the follow-up path. Nothing is padded and no sentence repeats another.

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

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

An output schema exists and annotations cover the safety profile, so the description does not need to explain return values. The one gap is that no parameters are marked required in the schema and the description never clarifies whether content is effectively mandatory, which matters for an agent assembling the call.

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%, including the maxLength on content and the document_title semantics, so the schema already carries the parameter burden. The description's media guidance ('from list_media, or a media_id from create_media_upload_url whose bytes you have uploaded') largely restates what the media_ids schema description already says, so it adds little beyond baseline.

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

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

The description gives a specific verb+resource ('Create a new LinkedIn post draft') and immediately qualifies the resulting state as '(unpublished)', which cleanly separates it from publish_draft and schedule_draft in the sibling list.

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 alternatives explicitly ('Publish it later with schedule_draft or publish_draft') and lays out the media prerequisite chain via list_media or create_media_upload_url. It stops short of stating when to use update_draft versus creating a new draft, so it is clear context rather than a full when/when-not matrix.

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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds genuine beyond-annotation context: the URL is one-time, the PUT must happen 'in this same runtime', and returned headers must be sent exactly. This is valuable operational disclosure, though it doesn't discuss auth/permissions or failure modes for the upload PUT itself.

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?

Well front-loaded (core purpose stated first) and structured with a numbered three-step flow plus a fallback clause. Each sentence carries operational value, though the description is on the longer side for a two-parameter tool and the final fallback sentence could be tightened.

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 multi-step tool with an output schema already defining return fields, the description supplies everything else an agent needs: the ordered flow, the same-runtime constraint, exact-header requirement, and a graceful degradation path. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented, including examples of content_type MIME values. The description clarifies why content_type is passed (the file's MIME type) and how the returned media_id is consumed, but adds no syntax or constraints beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Get a one-time presigned S3 URL to upload an image, video, GIF, or PDF') and ties it to a concrete downstream use. It effectively distinguishes itself from siblings like attach_media_from_url and upload_media by clarifying that the agent holds the bytes locally and receives a URL rather than uploading directly.

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 ('Use when the agent holds the bytes locally') and an explicit when-not/alternative ('If this runtime cannot PUT raw bytes to a URL, skip it: create a text-only draft and tell the user to attach the media in the Taplio composer'). The alternative path is named concretely, leaving nothing 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?

Annotations already supply destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=false, so the safety profile is covered. The description's 'permanently' adds only mild reinforcement of destruction and says nothing extra about permissions, whether the draft is recoverable, or error behavior on a bad/unowned id.

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?

One front-loaded sentence that carries the verb, resource, and permanence qualifier with zero filler. Nothing to trim.

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, fully-documented, annotated mutation with no output schema, the description is nearly sufficient. A short note on irreversibility/undo would close the remaining gap, but the annotations and schema carry most of the burden.

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

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

Schema coverage is 100% and the single id parameter is already documented, including its provenance from list_drafts. The description adds no format, ownership, or side-effect detail beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb (delete) and resource (LinkedIn post draft), with the qualifier 'permanently' that signals irreversibility. It distinguishes itself reasonably from get_draft/create_draft/update_draft, though it never names the closest alternative siblings (unschedule, cancel_comment_draft) to sharpen the boundary.

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?

No when-to-use guidance and no alternatives named. An agent cannot tell from the description whether to use this versus unschedule, cancel_comment_draft, or publish_draft-style workflows; usage must be inferred from the tool name 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 already declare readOnly, idempotent, and non-open-world, so safety is covered. The description adds real value beyond that: the filtering rules, the fact that each post costs one upstream call, and the returned identifiers (comment_urn, post_urn). It stops short of detailing pagination or error behavior, so not a 5.

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 front-loaded sentences with zero waste: what it returns, why comments are filtered, and the call-cost constraint plus the alternative input source. Each 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?

Output schema exists, so return values need not be explained, and annotations carry the safety profile. The description covers the remaining agent-relevant concerns: filtering semantics, batching guidance, and the upstream tool to source post_urns. Nothing needed 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 description coverage is 100%, so all four parameters are already documented, including the url/Enterprise constraint and the 1-10 post_ids limit. The description reinforces the post_urns semantics and batching but adds no syntax or format 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?

States a specific verb and resource (find comments on LinkedIn posts) plus a precise scope: only comments still worth a reply. The filtering criteria (already answered, wrote themselves, or hid) sharply distinguish this from siblings like find_posts_to_comment and list_comment_feeds.

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

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

Explicitly routes the agent: use post_urns from find_posts_to_comment, and ask for a handful of posts at a time rather than a whole page. It names the source of inputs and the operational constraint that drives batching, leaving little 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds real value beyond that by disclosing that every returned post carries a post_urn that downstream draft calls target, which is the key behavioral contract for chaining. It does not mention result volume or freshness, but that is minor given annotation coverage.

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 purpose and sources, then the post_urn contract, then the sibling routing rule. Every sentence earns its place 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?

Output schema exists, so return shape need not be explained, and the description covers the source selection, the urn handoff, and the alternative tool. Nothing an agent needs to call this correctly or chain it is missing.

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

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

Schema description coverage is 100%, so feed, source, limit and cursor are already fully documented in the schema (including the enum and the pointer to list_comment_feeds). The description only restates the three source values already listed in the schema and adds no new syntax or constraint detail, so baseline 3 applies.

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

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

States a specific verb (find) and resource (LinkedIn posts to comment on) plus the three sources it draws from, and implicitly separates itself from list_posts and search_inspiration. An agent can distinguish it from find_comments_to_reply without opening either schema.

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

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

Explicit workflow guidance: 'pick a post here first and draft the comment against that urn,' and an explicit alternative with its trigger condition — pass post_urn to find_comments_to_reply to reply to the discussion instead. When-to-use and when-to-use-something-else are both 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 already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds that it defaults to today's overview with no date range, but that default is already documented in the from/to schema descriptions, so the marginal behavioral value is modest.

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 core purpose and default behavior. The second sentence is a bit long but earns its place by broadening the use case beyond reporting; nothing is redundant 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?

An output schema exists, so return values need not be explained, and the schema fully documents the four optional parameters. The description covers scope, defaults, and the dual reporting/pre-drafting use case, leaving only pagination or rate-limit details unstated, which are minor here.

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%; every parameter (to, from, metrics, granularity) is documented, including the 90-day cap and the day-only enum. The description adds no further parameter meaning, 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?

The description states a specific verb and resource (get the user's LinkedIn analytics overview) and enumerates the metric families returned (followers, impressions, engagement). Account-level scope is clear enough to separate it from the per-post sibling get_post_analytics without opening either schema.

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

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

It gives explicit conditions for use: reporting on performance, and consulting it before drafting to see what is driving followers and engagement. It does not name a concrete alternative tool or state exclusions, so it falls short of a 5, but the context is clear.

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

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

Annotations only establish that this is a safe, idempotent read; the description adds the full state machine (draft/pending/posted/failed/cancelled) with the operational meaning of each, plus what failure_reason and failure_code represent. This is behavior beyond the annotations and beyond a bare fetch description.

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 resource, and every clause carries information. The middle status-enumeration sentence is long but each state's implication earns its place; minor tightening possible but no dead weight.

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

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

With an output schema present and annotations covering safety, the description supplies the remaining interpretive context an agent needs: the state lifecycle and what to check before reporting success. Nothing essential for correct invocation or interpretation is missing.

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

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

Schema description coverage is 100% and the single id parameter is already fully documented in the schema, including its provenance (from list_comment_drafts or create_comment_draft). The description adds no additional parameter meaning, 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 and resource: 'Fetch a single LinkedIn comment draft by id.' An agent can immediately separate this from siblings like get_draft, list_comment_drafts, or update_comment_draft 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?

Gives a clear workflow trigger: use this to 'confirm what a commit actually did' and read it 'before telling the user a committed comment is live.' That is strong when-to-use guidance, though it never names the alternative (e.g., list_comment_drafts for enumeration) or states when-not to call it.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, yet the description still adds substantial context: the full status vocabulary (pending/sent/failed/cancelled/skipped), what skipped_reason distinguishes, that nothing was sent to LinkedIn and no capacity was consumed, and the connection_not_found outcome.

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 read semantics, then statuses, then the follow-up guidance. Dense but every clause carries information; the skipped/account-capacity sentence is slightly long but 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?

An output schema exists, so return values need no explanation, and the description covers the non-obvious states an agent would otherwise misread (skipped vs failed, connection_not_found). Nothing needed 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% and the schema already explains that username is 'the same one send_connection_request was called with'. The description only adds the not-found behavior, so it is a marginal increment over the structured field – baseline 3 applies.

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

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

States a specific verb and resource ('Read back the latest connection request ... for a username') and implicitly scopes it to a single-request lookup, which separates it from list_connection_requests. The named lifecycle states make the resource identity 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?

Explicitly says 'Use it to follow up on a send_connection_request', giving the primary trigger. It stops short of naming list_connection_requests or cancel_connection_request as the alternatives an agent should prefer in other situations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is known. The description adds only the scope word "single" — it says nothing about not-found behavior, visibility/permission constraints, or whether draft content includes unpublished media references. Adequate but thin for a tool whose annotations do most of the disclosure.

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

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

One front-loaded sentence with zero waste; nothing is buried. It is arguably too terse to earn a 5, since brevity here comes at the cost of any usage or error guidance.

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 is a one-parameter read with an output schema and full annotation coverage, so the description does not need to explain return values or safety. What remains missing is minor: not-found behavior and how the id is obtained (the schema covers the latter).

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's schema entry even points at list_drafts as the source of the id. The description only restates "by id" and adds no format, validity, or sourcing semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb ("Fetch") and resource ("LinkedIn post draft") with the singular scope ("a single ... by id"), which distinguishes it from list_drafts and create_draft without ambiguity. It does not explicitly contrast with get_post or get_comment_draft, so no credit for named sibling differentiation.

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: an agent infers it should call this when it already has a draft id and needs the full record rather than a listing. There is no explicit statement of when to prefer it over list_drafts, nor any note about what happens for an invalid or deleted id.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the ai_settings shape and the caveat that a user may have several aliases, so both handle and name should be checked. It does not discuss caching or failure behavior, keeping 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?

The call-order instruction is front-loaded and the rest is a dense enumeration of returned fields with little waste. The single long sentence with an embedded em-dash aside is slightly hard to parse but never padded.

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

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

An output schema exists, so return values need not be spelled out; the description nonetheless summarizes the key payload groups an agent must act on. Combined with annotations covering the safety profile, 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?

The tool takes zero parameters, which sets the baseline at 4. There is nothing for the description to disambiguate, and it correctly spends no space on parameter guidance.

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 ('returns the user's identity and content preferences') and enumerates the actual payload: display name, @handle, ai_settings fields, and today's LinkedIn stats. No sibling tool overlaps this retrieval, so the purpose 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?

'Read this first to orient' gives an explicit call-order instruction, and the description explains the downstream purpose (tailor output, recognize the user's own posts). For a no-argument orientation tool with no competing sibling, this fully covers when to use it.

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

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

Annotations already declare readOnly/idempotent/closed-world, so the description doesn't need to restate safety. It adds genuinely new behavioral facts: LinkedIn urn ids only resolve within the last 90 days, and a post's status is limited to scheduled/sending/sent.

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 core action, and each clause carries information (id formats, time limit, status set, sibling exclusion). The trailing status enumeration is slightly tangential to fetching but aids interpretation.

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

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

With an output schema present and full parameter documentation, the description only needed to cover input formats, the recency constraint, and the boundary against drafts — all of which it does.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by defining that `id` accepts either a Taplio post id or a LinkedIn urn and constrains the urn case to a 90-day window — semantics the schema does not convey.

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 (fetch a single LinkedIn post by id) and immediately distinguishes the two id flavors it accepts. It also separates itself from the nearest lookalike, get_draft, in the same breath.

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

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

Explicitly routes draft fetching to get_draft and tells the agent where the id comes from (list_posts). It doesn't say when to prefer get_post over list_posts when listing would suffice, but the primary alternative is named and excluded.

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

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

Annotations already declare readOnly, idempotent, and closed-world, so safety is covered. The description adds genuinely useful behavioral detail the annotations lack — the 7-day default window and the semantics of media_type being absent when the format cannot be determined.

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 resource and returned fields; the second sentence adds the creative-reuse purpose without padding. Slightly loose in the trailing clause but no wasted sentences.

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

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

An output schema exists, so return shape need not be explained. For a read-only analytics tool the description covers scope, metrics, default window, and purpose adequately; only the sibling-overview distinction is missing.

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

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

Schema description coverage is 100%, so defaults, 90-day cap, and pagination are already documented in the schema. The description only restates the 7-day default and adds no date-format or cursor semantics beyond what the schema gives, so baseline 3 applies.

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

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

Names a specific verb (list) and resource (per-post LinkedIn analytics) and enumerates the returned metrics plus media_type, so the scope is unambiguous. It does not explicitly contrast itself with the sibling get_analytics_overview, though 'per-post' vs an overview is reasonably inferable.

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

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

Provides clear context for use: default 7-day window when no range is given, and a concrete job to be done ('find top-performing posts and reuse the topics, formats, and hooks'). It never states when not to use it or points at get_analytics_overview as the account-level alternative, so no exclusion 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 establish readOnly and idempotent behavior, but the description adds substantial context beyond them: exact status semantics (pending while queued, liked once sent, failed/cancelled with reason) and the like_not_found response for untracked likes. This is precisely the behavioral detail an agent needs to interpret results.

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, front-loaded with the core read operation, then the follow-up guidance and the key exclusion. Every sentence adds useful information 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?

An output schema exists, so return values need not be re-explained. Combined with the status semantics, error case, and clear pointer back to like_post, the description is complete for an agent to invoke and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the single post_urn parameter is already fully documented in the schema, including the warning that a post URL will be refused. The description does not add parameter syntax or format details beyond what the schema provides, so the baseline 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 states a specific verb and resource — 'Read back the latest like this account queued for a post or a comment' — and immediately enumerates the possible statuses (pending, liked, failed, cancelled). It is easy to distinguish from like_post because it explicitly frames itself as a follow-up read.

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

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

It gives an explicit when-to-use: 'Use it to follow up on a like_post.' It also defines an important when-not / edge case: likes created via the Taplio app's own like button are not tracked and return like_not_found. That removes ambiguity about what this tool covers.

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 idempotency, non-destructiveness, and open-world scope, but the description adds substantial context beyond them: the like is queued rather than sent, scheduled_for reports dispatch time, Growth plan is required with insufficient_plan as the failure signal, retries return the existing pending like, and post vs comment vs activity/ugcPost ids are distinct like targets. This is exactly the behavioral disclosure the structured fields cannot carry.

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

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

Dense but front-loaded: purpose first, then input forms, then queueing/plan semantics, then cancel. The second sentence is a long comma-chained list that could be split, but nearly every clause conveys operational information rather than 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?

With one parameter at 100% coverage and an output schema present, the description covers the remaining gaps an agent needs: deferred/queued execution, retry idempotency, plan gating, and the distinctness of post vs comment likes. Nothing material to a correct invocation is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes well beyond the schema by enumerating the accepted urn/url forms (activity urn, ugcPost urn, comment urn, post url, lnkd.in short link) and stating which sibling tool results supply each. That meaningfully reduces the risk of passing the wrong identifier.

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 (like) and resource (a LinkedIn post or a comment on one), immediately distinguishing the two object types it operates on. It also names the sibling cancel_like as the inverse operation, so an agent can tell what this tool does versus what undoes it 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?

Gives strong sourcing context: post_urn can come from find_posts_to_comment, list_posts, find_comments_to_reply, or raw user input, and it points to cancel_like for stopping a pending like. It stops short of an explicit when-not-to-use statement (e.g., preferring get_post_like for reads), which keeps it from 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 cover the read-only, idempotent, closed-world safety profile. The description adds non-obvious context: that a draft keeps one record for its whole life, making this both the queue and the history, and which statuses are mutable vs. final. That lifecycle model is genuine value beyond the annotations and schema.

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

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

Front-loaded with the verb and resource, then the lifecycle model, then usage. Three tight sentences with little waste, though the middle lifecycle sentence runs long and partly overlaps the schema's status descriptions.

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

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

With an output schema handling return values and full schema coverage of the three params, the description only needs to add the conceptual model and usage — which it does. An agent has everything required to invoke and interpret results 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%, and the status enum with its five meanings is already fully documented in the schema, so the description largely restates it. The only parameter-adjacent addition is the "newest first" ordering, so the baseline 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?

States a specific verb and resource ("List the user's LinkedIn comment drafts") plus the ordering ("newest first"). The "comment drafts" resource is naturally distinguishable from the general list_drafts sibling, though no sibling is named 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?

"Use it to find a draft to edit or commit, or to review what earlier commits did" gives clear when-to-use contexts. It stops short of naming the alternative tools (get_comment_draft, list_drafts) or stating when not to use this one.

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

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

Annotations already declare readOnlyHint, idempotentHint, and closed-world, covering the safety and idempotency profile. The description adds useful shape information (each feed bundles a hand-picked profile set and a count) but says nothing about pagination, ordering, or auth, so it adds moderate rather than rich 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?

Two sentences, no filler, and the core purpose is front-loaded ahead of the cross-tool linkage detail. 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?

An output schema exists, so return-value documentation is not required, and the description correctly focuses on the one thing the schema can't convey — that the returned name flows directly into find_posts_to_comment. Coverage is essentially complete for a no-arg, read-only list tool, with only a minor gap around ordering/pagination.

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 are zero input parameters, which is the baseline-4 case. The description sensibly spends no words on parameter syntax and instead explains the relationship between this tool's output and another tool's input.

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) plus resource (curated comment feeds available for engagement) and clarifies what each feed actually is — a hand-picked set of profiles with a tracked-profile count. It also names the sibling tool it feeds into, so the agent can distinguish it from generic listing tools like list_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 closing sentence establishes the workflow linkage explicitly: the returned name is exactly what find_posts_to_comment's feed parameter takes, which tells the agent when this tool is the right first step. It stops short of stating exclusions or prerequisite conditions, so it is clear context rather than full when/when-not 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 cover read-only, idempotent, and closed-world behavior, but the description adds meaningful lifecycle states, reason reporting for failed or cancelled requests, cross-Taplio scope, ordering, and the 100-item cap. The only small ambiguity is that 'skipped' appears in the duplicate-avoidance sentence without being included in the earlier status list.

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

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

The description is front-loaded and every sentence serves a purpose: lifecycle states, duplicate avoidance, cross-Taplio scope, and the alternative tool. It is slightly verbose but not padded.

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

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

With an output schema present, the description does not need to explain return fields. It provides enough context about ordering, statuses, scope, cap, and when to use the sibling tool 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 coverage is 100%, and the limit parameter is already fully described in the input schema. The description restates the newest-first ordering and 100-item cap but does not add parameter semantics beyond what the schema provides.

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 gives a specific verb and resource: list connection requests for the account, newest first, with status context. It also distinguishes the tool from get_connection_request by scoping this one to recent bulk listing versus checking one specific person.

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 to read this before sending a batch of connection requests so already pending, sent, or skipped people are not re-requested. It also names get_connection_request as the correct alternative for checking one specific person regardless of age.

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

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

The annotations already establish a read-only, idempotent, closed-world operation. The description adds useful result-scope context—only the user's unpublished drafts—but does not disclose further behavioral traits such as ordering or empty-result behavior.

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

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

Two short sentences front-load the exact operation and scope, then provide practical usage contexts. There is no redundant or unnecessary wording.

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 paginated read with an output schema and safety annotations, the description supplies the essential scope and selection context needed for correct invocation. Explicit sibling routing would be a refinement rather than a material omission.

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

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

Both parameters are fully documented in the schema, including limit's default and cap and cursor's pagination usage. The description adds no parameter meaning beyond that coverage, so the high-coverage 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 specifies the verb, resource, and scope: listing the user's unpublished LinkedIn post drafts. That scope distinguishes it from siblings such as list_posts, list_comment_drafts, and get_draft without requiring schema inspection.

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 concrete selection contexts: reviewing the content pipeline or finding a draft to edit, schedule, or publish. It does not explicitly route agents to get_draft for a known draft or to sibling list tools for other resources.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the sort order (most recent first), the fields returned, and the optional filtering behavior.

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

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

Two sentences, zero padding. What the tool returns and its ordering come first, then the actionable usage guidance. 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 read-only, zero-required-param list tool with full schema coverage, an output schema, and annotations covering safety, nothing is missing. The description supplies the ordering and workflow routing that structured fields cannot.

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 restates the query semantics ('filter by a filename substring') and omits limit entirely, adding no syntax or behavior beyond what the schema already documents.

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 (List) plus resource (media you've already uploaded to Taplio), and it enumerates the returned shape (id, type, public url, filename) and ordering (most recent first). It implicitly separates itself from upload_media/create_media_upload_url by stressing 'already uploaded', though it never explicitly distinguishes itself from pick_media.

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?

Clear workflow context: 'Use it before drafting so you can attach existing media via create_draft or update_draft media_ids — no re-upload needed.' That routes the agent to this tool instead of re-uploading. No explicit when-not or named alternative tool, but the intent is unambiguous.

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

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

Adds substantial behavior beyond annotations: ordering rules, date-window semantics under status=scheduled, LinkedIn-native 90-day coverage with daily-sync lag, and a clear warning not to retry for empty media. These details materially affect how an agent interprets results.

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

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

Front-loads the core listing behavior and scope, and most sentences carry operational value. It is somewhat long and spends multiple sentences on output caveats, but the structure remains purposeful rather than padded.

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

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

Complete for a complex listing tool: annotations cover safety and idempotence, the output schema covers returns, and the description fills key operational gaps around ordering, sync lag, draft exclusion, and media interpretation.

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 schema already documents all parameters. The description still adds value by explaining the interaction between status=scheduled and from/to, including that the date window shifts to scheduled date and results come back soonest first.

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 plus scope: the user's LinkedIn posts, newest first, including Taplio-created and LinkedIn-native posts. It also distinguishes posts from drafts and from engagement analytics, so an agent can identify the tool without opening the schema.

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

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

Explicitly routes metrics requests to get_post_analytics and gives a proactive use case before drafting. It implies drafts are handled by list_drafts but does not name get_post or list_drafts as alternatives, leaving some sibling routing implicit.

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

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

Discloses behavior the annotations cannot express: the panel is interactive and requires the user to click a tile, and the click attaches the selection to the given draft (consistent with readOnlyHint=false, destructiveHint=false). It also preempts a likely misconception by stating 'Nothing is uploaded.' It stops short of describing failure modes, whether the draft is modified immediately, or what happens if the user cancels the panel.

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 action and mechanism, then the use/avoid clause. Every clause earns its place; no restatement of the name or 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?

For a single-parameter, no-output-schema tool, the description covers the action, the interaction model, the side effect (attach to draft), and the sibling boundary. The only gap is what an agent observes after the user picks or dismisses the panel, which is minor.

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

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

Only one parameter, and the schema description coverage is 100% with a detailed draft_id entry (full UUID, never abbreviate). The description's 'the given draft' adds no syntax beyond the schema, 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 concrete action (open an interactive thumbnail-grid panel of library media) and the resource (images, videos, GIFs, PDFs already in the library). It also distinguishes itself from attach_media_from_url and upload_media by contrast, so an agent can route correctly without opening sibling schemas.

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

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

Explicit when-to-use ('reuse an asset they added earlier') and explicit when-not ('NOT for a file sitting on their machine'), naming the correct alternative tool (upload_media). Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is known. The description adds real context beyond that: the post goes live publicly right now and the action cannot be undone, which is the key consequence an agent must weigh before calling.

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 short sentences, purpose first, irreversible consequence second. No filler and nothing buried.

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

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

An output schema exists and the single parameter is fully documented, so the description only needed to convey purpose and risk, which it does. Naming the scheduled alternative would have made it complete for a mutation tool with several sibling paths.

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

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

Only one parameter, and the schema documents it fully (100% coverage) including its provenance from list_drafts. The description adds nothing about the id, so baseline 3 applies.

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

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

States a specific verb and resource ('Publish a LinkedIn post draft to LinkedIn immediately'), so the agent knows exactly what operation occurs. It implicitly separates itself from schedule_draft via 'immediately', but never names that sibling, so it falls 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?

The word 'immediately' implies this is the non-scheduled path, and the irreversibility warning implies caution, but no alternative is named and no when-to-use/when-not-to-use rule is stated. The agent must infer the schedule_draft distinction on its own.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=true, and openWorld=true, so the safety profile is covered. The description adds the meaningful behavioral fact that publishing happens automatically at a future time, but says nothing about what happens if a schedule already exists, failure behavior, or whether this replaces prior scheduling.

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?

A single sentence, front-loaded with the action and resource, with no filler. Every clause (LinkedIn, draft, auto-publish, future time) carries 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 two-param scheduling tool with full schema descriptions, an output schema, and annotations covering safety and idempotency, the description covers the essential behavior. Minor gap: no mention of interaction with existing schedules or of the unschedule/cancel counterpart.

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

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

Schema coverage is 100% and the schema itself is strong — id sourced from list_drafts, ISO 8601 format, and the 2-minute-future constraint. The description adds no parameter 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 (schedule) and resource (LinkedIn post draft) plus the effect (auto-publish at a future time). This implicitly distinguishes it from publish_draft (immediate) and unschedule, but the description never names those siblings 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?

Implied usage is clear from the verb — use this when you want deferred publishing rather than immediate publish_draft. But there is no explicit when/when-not guidance and no named alternative, so the agent must infer the routing.

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 well past the annotations by disclosing a hard cost model: each successful call and each further page consumes a daily search allowance that resets at 00:00 UTC, with tier-specific quotas (50/150/300). For an agent that may page results or retry, this is exactly the kind of budget information the readOnly/idempotent hints cannot convey.

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?

Purpose and the drafting use case are front-loaded, then the author shortcut, then the quota constraint last. The quota sentence is long but each clause (per-page counting, reset time, tier numbers) carries distinct information, so nothing is padding.

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

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

With 13 optional parameters, full schema coverage, and an output schema to describe returns, the remaining gaps an agent would care about are cost and filtering semantics — both covered. No contradiction with openWorldHint=false or idempotentHint=true is implied by the cursor-based paging.

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

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

Schema coverage is 100% and the schema descriptions already explain the query, author, date, and default behaviors in more detail than the description does. The description's one parameter statement ("Set author to read the posts one creator wrote") largely repeats the schema, so it adds value only by highlighting the most decision-relevant parameter; baseline 3 applies.

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

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

States a specific verb and resource ("Search LinkedIn posts from other creators") plus the intent ("use as inspiration"), which is far more than a restatement of the name. It doesn't explicitly contrast itself with lookalike siblings such as find_posts_to_comment or find_comments_to_reply, so an agent must infer the boundary from the word "inspiration".

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

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

"Use it before drafting to ground new posts in proven formats and angles" gives a concrete usage context rather than leaving timing implicit, and the author sentence tells the agent when to use that filter versus free-text query. No competing sibling is named and no when-not-to-use condition is given, which keeps it out of 5 territory.

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 well beyond the annotations: the invitation is queued and paced rather than sent immediately, scheduled_for reports the due time, repeat calls are deduplicated, already-connected or already-invited targets silently skip, and no note is attached by design. This is consistent with idempotentHint=true, destructiveHint=false, and readOnlyHint=false, and it discloses the async queue semantics an agent could not otherwise infer.

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?

Purpose and identifier are front-loaded, and every sentence carries real information (queue pacing, dedup, skip behavior, no-note policy, plan gate). It is dense for five sentences, and the Enterprise plan requirement buried near the end would be more useful up front.

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 an asynchronous, plan-gated, deduplicating mutation, the description covers the prerequisites, the side effects, the skip cases, and how to observe the outcome; the output schema already documents return fields like scheduled_for. 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?

Schema description coverage is 100% and the single parameter is well documented in the schema with the same 'jane-doe' example. The description's parenthetical restates that guidance rather than adding new syntax or format rules, 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 and resource ('Ask to connect with someone on LinkedIn') and disambiguates the single parameter's meaning ('public username, the last part of their profile url'). The naming of cancel_connection_request and get_connection_request makes clear this is the initiation step, not the cancel or status step.

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 strong operational context: safe to retry (duplicates return the same pending request), plan prerequisite (Enterprise, else insufficient_plan), and the alternative to use for stopping it (cancel_connection_request). It does not state when NOT to use it (e.g., for people already connected handled implicitly), so it falls just short of fully explicit routing.

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 the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description still adds real behavioral value by disclosing the state transition to drafts and the non-destructive, recoverable nature of the outcome; it does not cover auth requirements or error cases such as unscheduling a post that isn't scheduled.

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?

One sentence with zero filler, front-loading the action and ending with the practical outcome. 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?

The tool is simple (one required param, output schema present), and the description covers action, outcome, and follow-up options. Only edge-case behavior — what happens if the post is not currently scheduled, or idempotent repeat behavior — is left unstated.

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 `id` parameter is already documented, including its origin ('from list_posts'). The description adds no further meaning about the identifier, so the baseline 3 for schema-covered parameters applies.

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

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

The description names a specific verb and resource ('Unschedule a scheduled LinkedIn post') and states the resulting state ('returning it to drafts'), which distinguishes it from schedule_draft, publish_draft, and delete_draft 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?

It gives clear context for use: a post that is currently scheduled. The consequence sentence ('so you can edit, reschedule, or delete it') implicitly routes the agent away from delete_draft and toward this tool when the goal is reversible, but no sibling is named explicitly and no when-not-to-use condition is 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 already declare the safety profile (not read-only, idempotent, non-destructive), and the description adds genuinely new behavioral context: the state gate that causes rejection after commit. It does not cover permissions or rate limits, but the added constraint is substantive.

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: the action comes first and the editing constraint second. 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?

An output schema exists, so return values need not be explained. Purpose, the required parameters, and the key failure condition are all covered; only the recovery path after a rejected edit is left implicit.

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 (id and content, including length bounds and the list_comment_drafts origin) are already fully documented. The description's 'rewrite the text' only loosely maps to the content parameter and adds nothing over 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 and resource: rewriting the text of a LinkedIn comment draft, which cleanly separates it from update_draft (generic drafts) and create_comment_draft. It stops short of naming the sibling tool an agent might confuse it with, so it is clear but not fully differentiated.

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 concrete precondition: only a draft still in status 'draft' can be edited, and edits are rejected once it is queued or posted. That is an explicit when-not condition, though it does not point to an alternative tool for the rejected case.

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 non-read-only, idempotent, non-destructive behavior, so the bar is lower. The description still adds genuinely non-obvious semantics: content fully replaces the existing text, previously attached media is preserved automatically, and media_ids are additive only. It does not discuss permissions or rate limits, but for a draft-edit tool the important mutation semantics are disclosed.

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

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

Three sentences, front-loaded with the core action and scoped by the eligibility constraint at the end. Every sentence carries information, though the middle clause ('but media already attached is preserved automatically — you only pass media_ids to ADD media') is slightly tangled and could read more cleanly.

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

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

With an output schema present, return values need no explanation, and the description covers the draft-only constraint, replacement semantics, and additive media behavior. For a four-parameter tool whose schema is fully documented, this is complete enough to call correctly; only document_title interactions are left to the schema.

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 would be 3, but the description adds real meaning beyond the schema: it clarifies that media_ids are ADD-only and that existing media survives, and it names the source tools for obtaining ids. The only gap is document_title, whose behavior is left entirely to the schema.

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

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

States a specific verb and resource ('Update the content of an existing LinkedIn post draft') and immediately names the secondary capability (attaching media). The closing sentence restricts scope to drafts versus published/scheduled posts, which cleanly separates it from siblings like publish_draft, schedule_draft, and update_comment_draft.

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

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

Gives a clear when-to-use condition ('Only drafts can be edited — published or scheduled posts cannot') and explains that media_ids should come from list_media or create_media_upload_url, effectively routing the agent to prerequisite tools. It stops short of naming explicit alternatives for the non-draft case (e.g. pointing to publish_draft or unschedule), so it is strong but not exhaustive.

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 safety profile (not read-only, not idempotent, not destructive, closed-world), so the description need not repeat that. It adds genuinely new behavior: the tool opens an interactive panel requiring user interaction with a drop zone/chooser, which is critical to know before invoking. It does not cover failure modes or what happens if the upload is cancelled.

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, no filler. The interactive-panel mechanic and the file-type scope come first, and the routing rule to pick_media is placed last as a natural contrast. Every clause carries 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, no-output-schema tool, the description covers the interaction model, supported file types, and sibling routing. The remaining gap is that it says nothing about what happens after upload (return value, failure/cancel behavior), which matters since no output schema exists.

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

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

Only one parameter, and the schema already documents it fully at 100% coverage, including the uuid format and the warning not to abbreviate or reconstruct it. The description adds only 'the given draft,' which is redundant. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('uploaded to Taplio and attached to the given draft in one step'), names the accepted file types (image, video, PDF), and explicitly distinguishes itself from the sibling pick_media. An agent can tell this apart from attach_media_from_url and pick_media 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?

Gives an explicit selection rule — 'Use whenever the file is not in the library yet' — and names the alternative ('to reuse an existing asset instead, call pick_media'). The when-to-use and when-not-to-use conditions are both stated.

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