Iridium: LinkedIn MCP Server

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

With no annotations provided, the description carries the full behavioral burden and does so well: it warns that this publishes a public comment, appears on someone else's post under the user's name, and counts against their daily comment limit. These are exactly the side effects an agent needs before invoking a public posting action.

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 well structured with a clear warning, usage note, and parameter list. The trailing 'Responses: 200' section is low-value boilerplate given there is no output schema, but the rest is efficient.

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

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

Given the complexity of a public-posting action with three parameters and no annotations or output schema, the description covers purpose, required user consent, side effects, and every parameter's meaning and omission behavior. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: handle is tied to list_comment_drafts, comment_text is a replacement that can be omitted to post the draft as written, and comment_at accepts 'now', ISO-8601 with offset, or omission to let Iridium pick a time.

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: approve one comment draft and schedule it to post. It explicitly distinguishes the action as publishing a public comment, separating it from siblings like approve_content_draft or approve_reply_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?

It gives a clear usage condition: call only when the user has explicitly approved this specific comment. It also warns that the action counts against the daily comment limit. However, it does not explicitly name alternative tools like edit_comment_draft or skip_comment_draft for adjacent workflows.

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

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

With no annotations, the description carries the full behavioral burden. It strongly discloses that the action posts publicly, appears on the user's profile, and requires explicit approval, though it does not cover permissions, reversibility, or failure 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?

The key warning and usage condition are front-loaded, and the args section is efficient. The generic responses boilerplate adds little value, but overall it remains compact.

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 high-impact publish/schedule tool with no annotations and no output schema, the description covers the essential public-posting risk, approval condition, and all three parameters. It leaves some gaps around account requirements, reversibility, and error handling.

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 0%, so the description must compensate, and it does. It explains handle origin via list_content_drafts, post_text as final editable text and required, and scheduled_at as ISO-8601 with offset where omission publishes immediately.

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

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

The description states a specific action and resource: publish or schedule one of the user's own LinkedIn posts, generated from a content draft handle. It clearly distinguishes this from approval tools for comments and replies by naming LinkedIn posts and list_content_drafts.

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 precondition: call only when the user has explicitly approved this specific post. It also points to list_content_drafts as the source of the handle, but it does not explicitly name the relevant alternatives such as rewrite_content_draft or skip_content_draft.

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

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

With no annotations present, the description carries the full burden and it does so well: it flags 'THIS SENDS', notes that the connection request counts against the user's daily limit, and returns a draft_ handle that lets the agent skip list_scheduled. What it doesn't cover is failure behavior (what happens if the send is rejected or the daily limit is already hit) or the permission/auth model.

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?

Information is front-loaded: purpose first, the 'THIS SENDS' warning second, then the permission rule, then args. Every sentence carries weight. Minor deduction for the redundant title repetition at the top and slightly loose line breaks that add no value.

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

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

Given no annotations, no output schema, and zero schema coverage, the description covers purpose, consent semantics, rate-limit impact, return value, and all three parameters — enough to call it correctly. The remaining gap is error/failure handling and whether an approval can be reversed beyond the referenced cancel_scheduled.

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 0%, so the description has to define all three parameters itself, and it does: handle is tied to its producing tools; override_text spells out the non-obvious omission-vs-empty-string distinction (omit = send drafted text, "" = no note at all); send_at documents the literal "now", ISO-8601 with an offset plus an example, and the omit-and-Iridium-chooses default. This is meaningful semantics the schema cannot supply.

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 (approve) and a specific resource (one connection-note draft) and states the follow-on effect (schedule/send it). Naming the draft type as 'connection-note' distinguishes it from the sibling approve_comment_draft, approve_reply_draft, and approve_content_draft tools, so an agent can route correctly without opening a schema.

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

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

It explicitly sets the when/when-not condition: 'Call it only when the user has explicitly asked for this specific draft to go out. Finding or drafting something is not permission to approve it.' That exclusion clause is exactly the guardrail a tool with an irreversible send side effect needs, and it also points at the source tools (list_drafts, discover_prospects, run_outreach_pipeline) that produce the handle.

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

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

With no annotations, the description carries the full burden, and it does disclose several non-obvious traits: the action sends immediately, it schedules into an existing thread, it adds no new connection, and it does not consume the daily limit. It omits irreversibility, permission requirements, and what reschedule_send or cancel_scheduled would do afterward, leaving real gaps for a send operation.

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

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

The core sentence is well front-loaded and the send warning is prominent, but the trailing '### Responses: **200**: Successful Response' block is scraped OpenAPI noise that adds nothing for an agent and pads the definition.

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?

This is a sending/mutation tool with no annotations, no output schema, and 0% parameter documentation. The description would need to cover parameter meaning, send semantics, and reversibility to be adequate; it covers only the high-level effect, which is not enough for an agent to call it safely.

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 0% across three parameters, so the description must compensate and does not. 'Schedule it' faintly hints at send_at, but 'handle' and 'override_text' — the latter being a meaningful content-override switch — are entirely unexplained in both schema and description.

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

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

States a specific verb and resource ('Approve a reply draft') plus the effect ('schedule it into the existing thread'), which implicitly distinguishes it from approve_comment_draft / approve_content_draft / approve_draft siblings. It never names those alternatives explicitly, so differentiation is inferred rather than stated.

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 emphatic 'THIS SENDS' warns the agent that this is a dispatch operation, implying it should be used only once a draft is ready to go out. However, there is no explicit when-to-use guidance, no preconditions, and no routing to sibling tools like draft_reply, rewrite_reply_draft, or skip_reply_draft.

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

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

With no annotations, the description carries the full burden and does well: it discloses idempotency ('re-running is safe'), in-place repair of stale rows, the specific fields populated (kind, subject, real preview), and a 10-30 second runtime. It omits auth prerequisites beyond the 'after connecting LinkedIn' hint, rate limits, and failure 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?

Front-loaded with the core action and the single-pass contrast, then the operational details. Slightly redundant — the 'repair rows that predate those fields' idea is stated twice — plus schema boilerplate in the responses section, but no sentence is truly wasted.

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

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

For a zero-param, no-annotation, no-output-schema mutation, the description covers purpose, timing, idempotency, populated fields, and runtime. It could do more on prerequisites (which of the connect_linkedin_* tools must precede it) and on whether it returns a count or summary.

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

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

The tool takes zero parameters, so the baseline is 4; the description correctly implies no input is needed and doesn't waste words on nonexistent arguments.

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 (backfill/pull) and concrete resources (LinkedIn conversations from Unipile into Iridium) with an explicit scope contrast: 'every thread in one pass, not a page at a time,' which distinguishes it from the paginated list_chats/search_chats siblings.

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

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

Gives clear triggering conditions: run once after connecting LinkedIn, and re-run once after an upgrade to repair older rows. It does not explicit exclude other cases (e.g. 'do not use this to read chats during normal operation'), but the 'once after connecting' framing implies the boundary.

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

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

With zero annotations, the description carries the burden well: it declares this is not a LinkedIn-visible action ('Nothing is sent or changed on LinkedIn; it only stops looking') and that partial results survive cancellation. It omits whether cancelling is reversible, what happens if the job already finished, and whether a cancelled job can be restarted.

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 behavioral content is front-loaded in two tight sentences with no wasted wording. The trailing 'Responses: 200 Successful Response' block is boilerplate generated text that adds nothing and slightly dilutes the signal.

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 cancellation tool with no output schema, the description covers the important agent-facing facts: it's a local stop, not an outward action, and prior findings remain accessible. Missing only job_id sourcing and post-cancellation job state.

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

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

There is one required parameter (job_id, UUID) with 0% schema description coverage, and the description never mentions it — no guidance on where the job_id comes from (presumably get_job or a listing call) or what happens on an invalid/unknown ID. The prose compensates for nothing on the parameter side.

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 Job') and narrows the scope precisely: 'Stop a background search that has not finished.' That framing distinguishes it from get_job (which reads results) and from the many draft/scheduled-send siblings, none of which are background searches.

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?

Says when to call it (an unfinished background search) and what to use instead to retrieve partial output ('stays readable with get_job'). The condition 'has not finished' implicitly excludes completed jobs, but there is no explicit when-not-to-use or guidance on the already-finished/completed 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?

With no annotations, the description carries the full behavioral load and does most of it: it discloses state-dependent outcomes — no-op plus a message if already sent, a 'in the process of sending' report plus a recommendation to re-check list_scheduled, and that it prevents the item from ever reaching LinkedIn. Gaps remain around permissions, idempotency, and the error shape if the handle is stale.

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 state condition ('SCHEDULED but NOT sent') is front-loaded in the first sentence and the routing to the alternative follows immediately. The synonym list ('cancel invite, unschedule, pull back, stop sending, remove from queue') is somewhat padded and is the main thing that could be trimmed.

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

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

For a single-parameter mutation with no annotations and no output schema, the description covers the trigger, the prerequisite lookup, the postcondition, and both edge cases. It does not describe what a success response contains or what happens if the handle is unknown or already cancelled twice, which keeps it from a 5.

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 0%, so the description must compensate, and it does: it identifies 'handle' as the draft_ handle obtained from list_scheduled or approve_draft, which the schema only names as 'handle'. It stops short of showing the literal prefix format or what happens with an invalid handle, keeping it below a 5.

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

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

States a specific verb+resource ('Cancel a connection request (or message) that is SCHEDULED but has NOT been sent yet') with the scope explicitly narrowed by the queue state, which sharpens it well beyond the bare name. It also names the exact alternative (withdraw_connection_request) for the adjacent case, so the agent can distinguish it from siblings without opening a schema.

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

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

Gives explicit trigger phrasing ('cancel / stop / don't send / take back'), tells the agent to locate the item with list_scheduled, and names the exclusion: if already sent, use withdraw_connection_request instead. When-to-use, prerequisites, and the alternative are all present.

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

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

With no annotations, the description carries the load and does well: it discloses cache-first behavior, sequential provider calls with retries counted against `limit`, client-timeout risk at larger batches, `failed` semantics, and that linkedin_offer threads are auto-labelled with no model call. It does not state auth requirements or whether labels are persisted to the inbox.

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?

Core behavior, defaults, and the batching caveat are front-loaded with no wasted sentences. The trailing '### Responses: **200** ... Content-Type: application/json' block is auto-generated filler that adds nothing.

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

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

For a 2-param, no-annotation, no-output-schema tool it is nearly self-sufficient: it names the bucket outputs, the `remaining` / `failed` / `auto_labeled` fields, and the judging signals used per thread. The remaining gap is the absence of any statement about authorization or side effects on the inbox itself.

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 0% and both parameters are undocumented in the schema, so the description must compensate — and it does. It explains that `limit` counts provider calls (not threads), includes retries, defaults to 25, and recommends keeping it near 20 to avoid client timeouts; `taxonomy` is framed as an optional custom label list overriding the defaults.

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 — 'Triage the inbox into buckets' — plus the default label set and the per-thread confidence output. It is clearly distinct from thread-level siblings like summarize_thread or get_thread, though it never names an alternative explicitly.

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

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

Gives actionable usage context: cache-first, so repeat the call to drain a large backlog, and watch `remaining`. It also defines the default taxonomy so the agent knows what happens if it omits that arg. It stops short of explicit when-not-to-use or a named competing tool.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the prerequisite state and a minimal response contract (200 / application/json), but says nothing about failure behavior for an invalid or expired code, retry limits, or whether the account ends up connected or persisted on partial success. That is a meaningful gap for a mutation-style flow step.

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 operative instruction and the prerequisite are front-loaded in the first two sentences, and the Args block is compact. The leading header line 'Connect Linkedin Checkpoint Mcp' merely restates the tool name and earns nothing, which is the only real waste.

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

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

For a two-required-parameter tool with no annotations and no output schema, the description covers the prerequisite, both parameters, and the success status. It is usable as-is but incomplete on the error path, which matters most in a 2FA step where an invalid code is the common outcome.

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 0%, so the description must compensate, and it does: account_id is tied to the value returned by connect_linkedin_credentials, and code is tied to the code LinkedIn sent to email or phone. It adds real provenance and intent beyond the bare schema titles, though it omits format details such as code length or whether leading zeros matter.

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 body states a specific verb and resource: submit a LinkedIn 2FA verification code to complete the connection. It explicitly distinguishes itself from the sibling connect_linkedin_credentials by naming that tool's checkpoint=True output as the trigger, so an agent can tell the two apart without opening either schema.

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

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

It gives a clear, explicit condition for use: 'Use this after connect_linkedin_credentials returns checkpoint=True', which effectively names the alternative and the branch that selects this tool. It stops short of a when-not rule, e.g. what to do if checkpoint is False or if the code is rejected, so it is not fully 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?

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: the session is Unipile-managed and the existing browser session is untouched, and the 2FA outcome shape is described. Still missing for a credential-handling mutation: how the password is stored/transmitted, whether an existing connection is overwritten, and what happens on invalid credentials.

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

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

The core content is front-loaded and each sentence adds information — mechanism, non-interference with the browser session, then the 2FA branch. The trailing '### Responses: 200 Successful Response / Content-Type: application/json' block is auto-generated filler that contributes nothing.

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

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

No output schema and no annotations, so the description must cover return shape; it describes the checkpoint=True branch but not the plain success payload beyond the boilerplate 200 line. Combined with the undocumented country parameter, an agent can start the call but cannot fully predict the result.

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 0%, so the description must compensate, and it only partly does: username and password appear in the prose but get no format guidance (email vs handle, app password vs 2FA-wrapped). The third parameter, country, is never mentioned and is entirely undocumented — a notable gap since it likely affects session/geo behavior.

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

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

States a specific verb and resource ('Connect LinkedIn via username and password') plus the mechanism ('Creates a fresh Unipile-managed session'), which implicitly distinguishes it from the credential-free siblings connect_linkedin_url and connect_linkedin_li_at. It does not name those siblings explicitly, so differentiation is inferable rather than stated.

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 2FA branch is handled well: 'If LinkedIn requires 2FA, returns checkpoint=True with an account_id. Follow up with connect_linkedin_checkpoint.' That is a real when-to-use-next rule. However, nothing says when to choose this over connect_linkedin_li_at or connect_linkedin_url, or what to do if an account is already connected.

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

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

With no annotations, the description usefully discloses that authentication relies on a pasted session cookie and that no redirect is involved. It does not explain what happens after connection, whether credentials are stored, failure modes, or security implications, so the behavioral picture is only partially covered.

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

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

The description is short and front-loads the main purpose before the relevant cookie-acquisition steps. The redundant heading 'Connect Linkedin Li At' and boilerplate 200 response line slightly reduce efficiency, but the content is easy to scan.

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

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

For a two-parameter connection tool with no annotations, no output schema, and 0% schema coverage, the description adequately explains the required secret. It remains incomplete because it omits the country parameter and post-connection behavior, which an agent would need to invoke the tool confidently.

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 0%, so the description must compensate. It provides detailed guidance on obtaining and copying the required li_at value, but it never mentions the optional country parameter or its purpose, leaving one of two parameters undocumented.

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

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

The description clearly states a specific action and resource: connect LinkedIn by supplying the li_at session cookie. It distinguishes the method from OAuth and redirect-based flows, though it does not explicitly name or contrast the other connect_linkedin_* sibling tools.

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

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

It gives the necessary precondition—having a li_at cookie—and notes that this is lower friction than OAuth with no redirect, which implies when the method is appropriate. However, it never explicitly says when to use this instead of connect_linkedin_credentials, connect_linkedin_url, or connect_linkedin_checkpoint_mcp.

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

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

With no annotations, the description carries the behavioral burden and does disclose the important flow: returns a hosted-auth URL, user completes OAuth in browser, no password/cookie needed, and the connection is confirmed asynchronously via webhook. It omits details such as URL expiry/single-use behavior, auth requirements for calling the tool itself, and error cases.

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

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

The purpose is front-loaded in the first sentence after the repeated title, and the OAuth flow is described efficiently. The response boilerplate (200 content-type) is minor standard noise but does not obscure the useful content.

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

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

For a zero-parameter tool with no output schema, the description covers what the tool returns and how the user completes the flow. It is not fully complete because it lacks explicit sibling selection guidance and does not describe the response body beyond a 200 status/content type.

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

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

The tool takes zero parameters, so there is no parameter semantics burden; the baseline for a parameterless tool is 4. The schema coverage note is not relevant because there are no inputs to document.

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 a Unipile hosted-auth URL to connect LinkedIn. It distinguishes the mechanism from credential-based siblings by saying no password or cookie is needed, though it never names those sibling tools 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?

It explains the hosted OAuth flow and implies this is the no-credentials path, but it does not explicitly say when to use this instead of connect_linkedin_credentials, connect_linkedin_li_at, or connect_linkedin_checkpoint_mcp. For an agent choosing among several LinkedIn-connection tools, that routing guidance is only implied.

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses that the endpoint returns 501, creates nothing, and is disabled pending rebuilt per-recipient safety checks. That is exactly the behavioral context an agent needs to avoid a failed call.

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 critical information is front-loaded: disabled, returns 501, do not call, and alternatives. The trailing OpenAPI-style '200 Successful Response' boilerplate is unnecessary and somewhat misleading for a tool that actually returns 501, but the core message is tight.

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

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

Given that this is a disabled tool with no output schema and no annotations, the description is complete for its practical purpose: it prevents invocation and redirects to working alternatives. Detailed parameter semantics are less relevant because the tool cannot currently be used.

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 two required parameters at 0% schema description coverage, and the description does not explain name, steps, kind, template, or delay_days semantics. The phrase 'multi-step sequences' hints at the steps concept but does not compensate for the missing parameter documentation.

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 (create a multi-step sequence) and immediately clarifies effective behavior: the tool is disabled and creates nothing. It also distinguishes itself from the alternatives by naming schedule_manual_dm and schedule_chat_reply.

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

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

It gives an explicit prohibition — 'Do not call this' — and names concrete alternatives with the condition that selects them: approve one message now and schedule later follow-ups with schedule_manual_dm or schedule_chat_reply using a later send_at.

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

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

With no annotations at all, the description carries the full burden and does so well: it discloses immediate deactivation, session destruction, subscription cancellation, halting of scheduled work, 30-day data retention followed by permanent erasure, and separate audit retention. These are exactly the consequences an agent needs before invoking a destructive, irreversible-class operation.

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 effects are front-loaded and delivered as short, scannable clauses with no filler prose. The trailing "### Responses: 200 Successful Response / Content-Type: application/json" block is generated boilerplate that adds no value and slightly dilutes the otherwise tight structure.

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

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

For a zero-parameter destructive tool with no output schema, the description covers consequences, timing, and data lifecycle thoroughly. It stops short of stating whether a confirmation step or specific auth is required, and whether the 30-day retention window allows restoration.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. It correctly implies no configuration is needed — deletion is all-or-nothing.

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 ("Delete your Iridium account") and adds scope detail — LinkedIn session destroyed at Unipile, subscription cancelled — which distinguishes it from the otherwise similar disconnect_linkedin sibling. It never names that sibling explicitly, so the differentiation is implicit rather than spelled out.

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

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

Usage is implied by the severity of the described effects ("All scheduled work stops at once"), which signals this is a terminal action rather than a routine one. However, there is no explicit when-to-use/when-not guidance and no named alternative such as disconnect_linkedin for users who only want to unlink LinkedIn.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the connection is removed from Unipile, cleared from the profile, and that all LinkedIn-dependent functionality stops until reconnection. It does not state permission requirements or whether any historical data is retained, but the core effects are well 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?

The description is short and front-loads the key effect and consequence. It wastes some space repeating the tool name as a heading and includes boilerplate response formatting, but the substantive content is efficient.

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

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

For a zero-parameter disconnect operation without annotations or an output schema, the description gives enough context to understand the action and its immediate impact. It could be slightly more complete by stating whether reconnection requires full authentication again, but the essential behavior is covered.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain. The baseline for a zero-parameter tool applies, and the description correctly avoids unnecessary parameter commentary.

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

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

The description states a specific verb-resource pair: disconnecting the LinkedIn account from Iridium. It also names the concrete systems affected, Unipile and the user profile, making the operation distinguishable from sibling connection tools such as connect_linkedin_* and broader destructive tools like delete_account.

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

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

The description explains what happens after disconnection, but it does not say when an agent should choose this tool over alternatives, nor does it name any alternative tools. There are no explicit exclusions or prerequisites for deciding to disconnect versus, for example, deleting the account.

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

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

With no annotations, the description carries the full burden and does: 10-40s synchronous path vs background job with job_id, notification by email on finish/pause, cost in actions (~11 for 5 people), and the critical safety fact that nothing sends until approve_draft and drafts persist indefinitely in pending_review. These are exactly the traits an agent can't infer from the schema.

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

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

Headings and front-loading are strong and the cost/behavior facts are placed where an agent needs them. It is longer than necessary in places, repeating the group-vs-named distinction and restating the action cost in two sections, which costs it the top score.

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

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

There is no output schema, so return values must be in prose — and they are: up to 3 results inline, otherwise a job_id with drafts surfaced via list_drafts and get_job, plus the full profile field list to display next to the note. Nothing needed to call or interpret results 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 0%, so the description must compensate and it does: query and location get example formats, limit gets its range and default, hiring_only is defined as the profile badge rather than post text with its application point (after profile fetch, no extra cost) and a pointer to search_posts_by_topic for the post-text question, and open_to_work_only's OR interaction with hiring_only is spelled out.

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?

Opens with specific verbs and resources ("Search for people, read their profiles, and generate connection note drafts") and then explicitly separates itself from find_person, find_prospects/search_prospects, search_posts_by_topic and run_outreach_pipeline. An agent can classify a request against this tool 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?

Provides an explicit decision rule (named person vs described group), worked example utterances for each branch, an explicit NEVER list for both directions, and a disambiguation protocol for the ambiguous case that says to ask one question rather than guess. This is about as complete as usage guidance gets.

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

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

With no annotations, the description carries the burden and does disclose the important behavior: this creates a *pending* draft rather than sending anything, uses the full thread plus the user's voice, and is limited to one draft per thread. It omits what happens on a duplicate request (error vs. replace) and any permission or rate-limit constraints.

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

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

The core sentences are tight and front-loaded, but the repeated title "Draft Reply" and the trailing "### Responses: **200**..." OpenAPI boilerplate add text that does not help an agent invoke the tool.

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

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

For a two-parameter creation tool with no output schema, the description covers what it makes, what it doesn't do (send), the review path, and both inputs. Missing only the return shape and duplicate-draft handling, which are minor given 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?

Schema coverage is 0%, so the description must compensate — and it does, documenting both parameters: chat_handle's provenance ("from list_chats / search_chats / list_replies") and intent as an optional goal-or-tone steer. It doesn't describe the handle's format, though that is acceptable given it is an opaque token from sibling tools.

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 ("Generate a reply to a conversation") and pins the scope ("Creates a pending reply draft, one per thread"), which separates it from rewrite_reply_draft and approve_reply_draft. It does not name those siblings explicitly, so the differentiation is implied rather than stated.

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

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

Gives clear usage context: generate a draft "for review" and then "Approve, rewrite, or skip it next," which maps the agent onto the correct follow-up tools. It stops short of explicit exclusions (e.g., when to prefer getting a thread summary first or when a draft already exists).

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

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

With no annotations, the description must carry behavioral disclosure. It usefully states that the tool saves only and does not post, and that approval is separate, but it does not cover permissions, whether the edit overwrites existing text, behavior when no updated content is supplied, or response details.

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 functional content is front-loaded and reasonably brief, but it repeats the title, includes an Args section, and adds boilerplate about a 200 response and application/json content type that does not help tool selection or invocation.

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

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

For a mutation tool with no annotations and no output schema, the description covers the main save-versus-post distinction and the handle. However, the parameter-name mismatch and missing permission/overwrite behavior leave notable gaps 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 0%, so the description needs to clarify both parameters. It explains the handle as a cdft_ value from list_comment_drafts, but refers to the text parameter as 'comment_text' while the schema defines 'updated_content'; this mismatch creates confusion, and the nullable updated_content behavior is unexplained.

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: edit a comment draft by replacing its text with text the user wrote. It also distinguishes saving from posting and approving, giving an agent a clear sense of the operation, though it does not explicitly contrast edit_comment_draft with rewrite_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?

It gives a clear usage condition: 'Use this when the user dictates their own wording,' and clarifies that approving is still a separate step. It does not explicitly name the alternative rewrite tool, but the when-to-use guidance is strong.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses the single most important trait: the tool fails with 501 and has no side effects. It adds no detail about what enrollment would do if re-enabled or what the error payload looks like, which keeps it short of 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?

'CURRENTLY DISABLED' is front-loaded where it will be seen first, and the alternative follows immediately. The trailing '### Responses: 200 Successful Response' block is leftover boilerplate that is arguably misleading given the 501 behavior.

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 disabled tool with two opaque params and no output schema, the description supplies everything an agent actually needs: do not call it, use create_sequence, schedule manually. Parameter documentation would be nice but is low-value while the endpoint is inert.

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 0% and both required parameters (prospect_handle, sequence_handle) are undocumented in the schema, yet the description says nothing about their format or where the handles come from. Since the tool is unusable this matters less, but the gap is real.

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 verb+resource ('Enroll Prospect') is clear, and the description immediately qualifies it with 'CURRENTLY DISABLED ... enrolls nobody', so an agent knows exactly what the tool would do and that it currently does nothing. It doesn't explicitly state what enrollment means (prospect into sequence), but the parameter names and sibling set make that 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?

Explicit when-not ('This tool returns 501 and enrolls nobody') plus a named alternative ('See create_sequence') and a concrete fallback ('Schedule follow-ups explicitly instead'). This is the strongest possible routing guidance for a dead tool.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it says drafts nothing, explains read costs, caching, budget exhaustion, match limits, verdict semantics, and background job behavior for larger batches. It also clarifies that handling writing requires passing the returned handle to schedule_dm_to_person.

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 well structured, opening with purpose and routing guidance before arguments and returns. It is still quite long and repeats cost and drafting details in multiple sections, so it is slightly verbose rather than maximally concise.

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

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

Given nine parameters, no annotations, no output schema, and zero schema descriptions, the description is remarkably complete. It explains return fields, verdict meanings, proof behavior, job_id flow for more than three people, and next-tool handoff, leaving no material gap 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 0%, but the description documents every parameter with examples, defaults, and meaning: name surname handling, past vs current company, location, title, soft keywords, evidence, include_history, and the people list alternative. This fully compensates for the schema gap.

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: find ONE specific person by name, optionally pinned by past employer. It explicitly distinguishes this from discover_prospects and from list-oriented tools like find_prospects/search_prospects, so an agent can route correctly without opening schemas.

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

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

It gives explicit when-to-use, when-not-to-use, and alternatives, including concrete user phrasings. It also handles the ambiguous case by instructing the agent to ask one clarifying question and then call exactly one tool.

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

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

With no annotations at all, the description carries the full burden and does so in detail: per-candidate touch cost, free cache reuse, the fact that max_touches>3 returns a job_id and emails the user on completion, background_touches results arriving only on a later call, and the explicit guarantee that budget exhaustion returns a populated list with budget_exhausted set rather than an empty list. It also discloses plan-dependent behavior (full Recruiter seat confirms open-to-work for free; Recruiter Lite falls back to order-then-confirm; posted_recently works only on Sales Navigator with a tier_note otherwise). This is exactly the behavior an agent cannot infer from schema or annotations.

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

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

Front-loaded and sectioned: purpose, default-usage claim, phase ladder, badge-vs-post-text distinction, honesty contract, then arguments — an agent can stop reading once it has what it needs. However the badge/cost story is told three or four times over (the 'who HAS the #hiring badge' line, the BADGE vs POST TEXT block, then again inside the hiring and open_to_work arg entries), so several sentences restate prior ones rather than earning new space.

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 13-parameter, no-annotation, no-output-schema tool with tier-dependent branching, this is close to complete: it names the response fields an agent must read (checked, cached, confirmed, budget_exhausted, tier_note, background.queued) and cross-references get_job and list_drafts, which compensate for the missing output schema. The remaining hole is that the three overlapping prospect-search siblings are never disambiguated, leaving the agent's tool-selection decision only partly closed.

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 0% and there are 13 parameters, so the description must compensate entirely — and it documents all 13, including ranges/defaults (limit 1-100 with a note that classic plans cap at 10; max_touches 0-10 default 0), filter-combination logic ('any-of within a filter, all-of across filters'), and enum meaning for network_distance (DISTANCE_1 = direct connections). Crucially it also clarifies what a flag does NOT mean (hiring = profile badge, not post text) and what happens to the flag on unsupported plans, which is semantics no schema could carry.

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 verb+resource chain ('find people on LinkedIn and, optionally, verify and write to a few of them') and explicitly declares itself the default for 'find me people who...' requests, which is far more than a name restatement. It sharply differentiates from search_posts_by_topic, but says nothing about the two most confusable siblings, search_prospects and discover_prospects, whose names an agent could easily mistake for this one.

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 unusually explicit when-to-use routing for search_posts_by_topic ('who POSTED about hiring' vs 'who HAS the hiring badge') plus a clear decision ladder over max_touches=0 / N / want_notes and background_touches, framed as cost tradeoffs. The gap is that it offers no exclusion or comparison against search_prospects or discover_prospects, so the agent is told 'use this as default' without being told what those siblings are for or when they'd win.

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

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

No annotations exist, so the description carries the full load and does well: it discloses the inactivity window, the scheduled-reply exclusion, the non-obvious sort order, and — importantly — that hiring_signal comes from a cached prior profile fetch and 'never a new one,' so no side effect occurs. It also warns that false is not a confirmed negative. It never states pagination/truncation behaviour, which is the main behavioral gap.

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 body is front-loaded and well structured: purpose, then a scannable bullet list of the two thread states, then exclusions, sort order, and the hiring_signal caveat. The trailing '### Responses / 200 / Content-Type' block is generated boilerplate that adds nothing and is the only real waste.

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

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

With no annotations and no output schema, the description still covers the shape of the result set (stale state labels, ordering, the hiring_signal field and its epistemic status), which is the hard part. The remaining gap is result-count/pagination semantics, which matters for a default-limited list tool.

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

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

Schema description coverage is 0%, so the description must document both parameters and does not. `days` is only echoed as 'threads with no activity in `days`' with no mention of the default of 7. `limit` is never mentioned at all, so an agent cannot tell that results are silently capped at 50.

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 Stale Threads') and then operationally defines the result set with the ghosted / owed_reply split and the exclusion of threads with a pending scheduled reply. An agent knows exactly what set comes back. It stops short of naming how it differs from siblings like list_chats or search_chats, which share the inbox surface.

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

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

Usage is implied by the definitions — this is the triage tool for dropped balls, and the exclusion rule tells you when a thread will not appear. But there is no explicit 'use this instead of list_chats when…' and no stated preconditions (e.g. LinkedIn connection state) that would route the agent between inbox tools.

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

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

No annotations are provided, so the description carries the burden and does so well: it declares 'Nothing is sent or changed by calling it' (read-only safety), discloses newest-first ordering, cursor pagination, and the retention-window caveat where target names may be erased. Missing only things like rate limits or result-size ceilings.

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

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

Front-loaded with purpose and safety before the usage triggers and arg docs; every section serves a purpose. The quoted example queries add real routing value, though the entry-field enumeration borders on verbose.

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

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

Despite no output schema and no annotations, the description specifies the returned entry fields (at, action, surface, status, target, summary, detail, error) and the pagination contract via next_cursor. An agent has everything needed to call it and interpret results.

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

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

Schema description coverage is 0% and the schema has no enums, yet the description documents every parameter: limit (1-100, default 20), cursor (next_cursor from prior call), surface values ('linkedin'/'iridium', omit for both), status values ('success'/'failed'/'skipped'), and action_type as an exact slug with an example. This fully compensates for the schema gap.

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 the user's activity log'), its scope ('Every action Iridium has taken, newest first'), and its backing store (append-only ledger). An agent can immediately distinguish it from narrow siblings like get_last_action.

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 trigger conditions with concrete example queries ('what did you do today?', 'what failed?') and a strong directive to answer from the log rather than conversation memory. It does not name alternatives such as get_last_action for single-action lookups, so no exclusion guidance exists.

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

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

With no annotations present, the description carries the burden and does state 'Read-only' plus what content is returned, which is the key safety signal for a read tool. It does not cover failure modes (missing/invalid handle, cross-account access), which is the remaining gap.

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 effect and the return contents, then usage guidance; every prose sentence earns its place. Deducted for the redundant 'Get Draft Detail' header and the stray '### Responses: 200' boilerplate, which add nothing and mimic an output schema that doesn't exist.

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 read tool with no output schema, the description says what comes back and how to get the handle, which is close to sufficient. Missing only the failure/edge behavior an agent would want when a handle is rejected.

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 0%, so the description must compensate; it does so by naming the parameter, giving its expected format ('draft_ handle') and its source (from list_drafts). That is enough for correct invocation, though it doesn't describe error behavior for a bad or stale handle.

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 one connection-note draft's full detail) and enumerates the payload: full note text, the angle it was written from, and the addressed profile. It also explicitly contrasts with list_drafts previews, so an agent can pick between them 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?

Gives two concrete trigger conditions ('user asks why a draft says what it says' or 'wants the full text') and names the alternative (list_drafts) plus why it is insufficient (it only previews). That is explicit when-to-use with the alternative surfaced.

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

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

With no annotations, the description carries the full burden and does so: background/asynchronous execution, email notification at pause/finish, partial-result streaming, and the fact that results carry a `handle` usable with other tools. It enumerates every status value with its meaning, including the throttling case (waiting, resume_at, auto-resume) and the 'wait a day' case, plus guidance that `message` is safe to relay verbatim.

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 action, then structured into behavior, status enumeration, and an Args block, all of which earn their place. A few phrases are conversational filler ('do not make you wait', 'it says it in plain words'), and the status list is dense but necessary for polling logic.

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 2-param, no-annotation, no-output-schema tool, the description covers execution model, return shape (status, done count, results, handle, message) and status lifecycle. The remaining gap is pagination: it says limit is 'most results to return' but never says whether more results exist beyond the limit or how to fetch them.

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 0%, so the Args block is doing real work: job_id is explained as 'the job to read, omit to list the latest 10' — behavior the nullable schema does not convey — and limit is described as max results. The limit text largely restates the schema's min/max/default, and the interaction between limit and job_id (does limit apply to listing jobs or to results?) is not spelled out.

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 the verb and resource precisely ('check on a search that is running in the background, and read what it has found so far') and covers both modes: with job_id you read one job, without it you list the latest jobs. An agent can distinguish it from siblings like cancel_job or get_activity_log from the text alone.

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?

Explains the triggering context well: large searches return a job_id instead of blocking, and you can work on partial results while the rest runs. It also tells the agent when to omit job_id (list latest 10). It stops short of naming alternatives or explicit exclusions (e.g., use cancel_job to stop a job), so it is clear context rather than a full routing rule.

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

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

With no annotations, the description explicitly discloses the safety profile ('Nothing is sent or changed by calling it') and the empty-state return ('{"item": null} if the account has no recorded actions yet'). It omits any note on auth or rate limits, but for a zero-parameter read this covers nearly all behavioral risk.

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 prose portion is tight and front-loaded, but the description is padded with auto-generated boilerplate ('### Responses: **200**: Successful Response ... Content-Type: application/json') that conveys no decision-relevant information. The restated title line also adds nothing.

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

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

There is no output schema, yet the description discloses the null case and that the full action text is returned, and it states the operation is side-effect free. It stops short of enumerating the fields of a non-null action item, which is the only remaining gap for a caller.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a parameterless tool applies. No misleading parameter language is introduced.

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?

Opens with a specific verb and resource ('read back the single most recent action Iridium took') and states the returned payload ('with its full text'). This is immediately distinguishable from the sibling get_activity_log, which returns a broader history.

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 triggers ('to confirm something just happened, after approving or scheduling anything, or when the user asks "did that work?"') and names the alternative with the condition that selects it ('cheaper than get_activity_log when only the last action matters'). Both when-to-use and when-to-use-something-else are covered.

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

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

With no annotations, the description carries the full burden and does so: it discloses the per-person cost against a daily budget, the background-job threshold (>3 handles, up to 50, returns job_id readable via get_job, user emailed on completion), and that opening the profile is what reveals the is_hiring / is_open_to_work badges. It also documents the return payload shape, none of which is in 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?

Well front-loaded: purpose first, then the three-tool ordering, then constraints, cost, and return shape. Some repetition creeps in — the find_prospects comparison and the badge/touch cost point are restated in the final paragraph — but the length is largely justified by the volume of decision-relevant 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 9-parameter tool with 0% schema coverage, no annotations, and no output schema, the description supplies everything needed: input constraints, cost model, async behavior, and the concrete response shape including the fields each result carries. Nothing an agent needs to call it correctly or interpret results 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 0% across 9 parameters, so the description must compensate, and it largely does: it states the at-least-one-of constraint across name/linkedin_id/iridium_handle/linkedin_ids/iridium_handles, expresses a preference ordering ('Prefer iridium_handle(s)'), and explains that name plus the hint fields is a keyword search opening up to 5 profiles. It does not explain the format expected for linkedin_id versus iridium_handle, which is the remaining gap.

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 the full LinkedIn profile(s)') with scope clarification ('people you already know, or several at once'). It explicitly contrasts itself against the two sibling tools find_person and find_prospects in a labelled ordering block, so an agent can distinguish the tools without opening 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?

Gives an explicit numbered workflow with when-to-use conditions ('Call it only when find_person's headline and proof are not enough') and when-not conditions ('to resolve a name, use find_person'; 'to find people you cannot yet name, use find_prospects'). It also names the alternative path for existing conversations (search_chats + schedule_manual_dm) and warns against messaging from a 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?

With no annotations at all, the description carries the burden and does well: it discloses that reads are local-first with no Unipile quota consumed once synced, that messages return oldest-first, and that paging walks backward through history. It omits what happens when a thread has not been synced yet (does it trigger a sync, fail, or return empty), which is the main remaining behavioral unknown.

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

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

The core prose and the Args block are tight and front-loaded, but the repeated 'Get Thread' header and the '### Responses: **200**: Successful Response (Success Response) Content-Type: application/json' boilerplate add no information and should have been stripped.

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 read tool with no annotations and no output schema, the description covers quota behavior, ordering, and pagination, which is what an agent needs to call it correctly. It does not describe the shape of the returned message objects or the next_cursor field itself, leaving the agent to discover the response structure at call time.

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 0%, so the description must compensate, and it does: every one of the three parameters is explained, including the source of each value. It adds real meaning beyond the schema by stating the max of 50 for `limit`, which appears nowhere in the schema (which only shows default 10).

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 a full LinkedIn conversation with one person') with a clear scope that separates it from list_chats/search_chats (which only supply the handle). It never explicitly contrasts with summarize_thread, the closest sibling that also operates on a thread, 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?

Gives concrete guidance on provenance ('chat_handle from list_chats / search_chats') and on when to use the `before` parameter ('pass the returned next_cursor to scroll up into older history'). No explicit when-not-to-use or exclusion against summarize_thread, so it is clear context rather than full 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?

With no annotations, the description carries the burden and explicitly states that the operation is read-only and what account-state data is exposed. It also adds the useful behavioral detail that setting field names match update_settings, allowing read values to be written back directly. It does not discuss permissions, authentication, or data freshness, so it is strong but not fully exhaustive.

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 useful information is front-loaded: purpose, returned state, read-only status, and usage guidance appear immediately. The trailing Responses section is boilerplate API output and does not add much, but it is not large enough to undermine the otherwise efficient structure.

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

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

Given a zero-parameter, read-only tool with no output schema, the description is complete enough: it explains what the tool returns, when to use it, and how it relates to update_settings. An agent has sufficient information to decide whether to call it and how to interpret its role in the workflow.

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

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

The tool takes zero parameters, so there are no input semantics to document; the baseline for zero parameters is 4. The note that setting fields align with update_settings is useful context but does not change the parameter semantics of this no-argument call.

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

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

The description uses a specific verb (Get) and resource (User Profile) and enumerates the account state it returns: targeting/voice settings, daily limits and usage, pending drafts, queued sends, unread replies, and LinkedIn connection status. It also distinguishes the read-only nature from update_settings, so an agent can tell what this tool does without opening the schema.

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

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

It gives explicit when-to-use guidance: check before any bulk action to assess remaining capacity, and check before asking the user for a setting because it may already be set. It also frames the tool as read-only, making clear that write operations belong elsewhere, especially update_settings.

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

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

With no annotations present, the description carries the full burden and does add two valuable behavioral facts: the tool reads a synced copy and consumes no LinkedIn quota. However, it says nothing about freshness/staleness of the synced data, result volume, or whether the full history is returned given there are no pagination parameters.

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 useful content is front-loaded and tight, but the payload opens with a redundant "List Chats" heading and ends with auto-generated noise ("### Responses: **200**: Successful Response ... Content-Type: application/json") that conveys nothing an agent needs.

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

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

There is no output schema, so the description must explain the return shape; it only offers the odd phrase "Returns chat_ handles for ...", which hints at an identifier field without documenting it. For a list tool that presumably returns a collection, more on return fields or ordering guarantees would be expected.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is no parameter meaning for the description to add or omit.

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 (list the user's LinkedIn conversations) plus ordering semantics (most recent first) and data source (Iridium's synced copy). It names downstream consumers (get_thread, summarize_thread, draft_reply, schedule_manual_dm) and backfill_chats, which helps an agent place it in the workflow, but never explicitly contrasts with the sibling search_chats.

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?

"If the inbox looks empty on a new account, run backfill_chats once" is explicit conditional guidance with the correct alternative tool named. It also clarifies that this is the feeder for thread-level tools. It lacks an explicit when-not (e.g. use search_chats when you need filtering), so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It contributes useful instructions to display every draft in full and not to approve drafts implicitly, but it does not explicitly confirm read-only behavior, pagination, ordering, or other operational traits.

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

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

The purpose is front-loaded and the display instructions are relevant, but the description repeats the title and includes a boilerplate 200 response note that adds little value. Overall it remains appropriately sized.

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

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

With no output schema and no annotations, the description should do more to explain the returned draft structure. It mentions author_name, post_text, and comment_text in the display template, but omits identifiers or other fields an agent might need to act on a draft.

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

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

The tool has zero parameters, so there is no parameter semantics to explain. The schema coverage is complete and no additional parameter guidance is needed.

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

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

The description states a clear verb and resource: it lists pending comment drafts awaiting review. The resource name distinguishes it from reply drafts and content drafts, but the description does not explicitly explain how it differs from the generic sibling list_drafts.

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 establishes the usage context as reviewing pending drafts and explicitly warns not to call approve_comment_draft or schedule anything unless the user asks. However, it does not explain when to choose this tool over list_drafts or list_reply_drafts.

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

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

No annotations exist, so the description carries the full burden and does: it discloses the return shape (name, headline, optional note, existing inbox message, accept/maybe/decline suggestion with confidence) and the non-obvious side effect — a stale list (reviewing true) triggers a background review and an outbound email, so the agent should inform the user and not block. It even reconciles the 'read-only' claim with that side effect rather than hiding it.

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 is front-loaded and the ask-first warning appears before the detail block, which is the right ordering. Deductions for the redundant title restatement ('List Connection Requests') and a thirteen-item synonym enumeration that could be trimmed without losing routing signal.

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

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

For a no-parameter tool with no annotations and no output schema, everything an agent needs is present: what it returns, that it can spawn an async background job and an email, and how to communicate that to the user. Nothing material is left to inference.

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

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

The tool takes zero parameters, so the baseline is 4. The description goes beyond that only by describing the response fields, which is useful but not parameter semantics.

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 and directionality: 'List the connection requests the user has RECEIVED and not yet answered.' The uppercase RECEIVED and 'not yet answered' scope cleanly separate it from siblings like list_sent_connection_requests, respond_connection_request and withdraw_connection_request 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 example user phrasings ('how many connection requests do I have', 'check my invites'), an explicit ask-first rule for ambiguous mentions, and named exclusions — 'Do NOT use to send connection requests (outreach tools), to read or send messages (list_chats / get_thread)'. Alternatives and when-not conditions are both spelled out.

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

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

No annotations are provided, so the description carries the burden; it does convey read-only intent ('List', 'Nothing here has been published') and that drafts are returned in full for user review, with publishing kept as a separate action. It says nothing about pagination, volume limits, or ordering, which matters for a list endpoint with no output 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?

Purpose is front-loaded in the first two lines and the sibling differentiation is compact. The trailing '### Responses: 200 ... Content-Type: application/json' block is API boilerplate that adds no selection value and slightly dilutes the payload.

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

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

For a zero-param read tool with no output schema and no annotations, the description supplies what matters: scope, what the records are, what they are not, and that review/publish is a separate step. Missing only return-shape details (fields per draft, ordering), which is a modest gap given the tool's simplicity.

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

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

The tool takes zero parameters, so the baseline is 4; the description correctly implies no filtering arguments are available rather than claiming any narrowing controls. No parameter-related compensation is needed.

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

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

States a specific verb and resource ('List Content Drafts', the user's own LinkedIn post drafts') and immediately narrows scope with 'waiting for review. Nothing here has been published.' It explicitly distinguishes itself from the near-identical siblings list_comment_drafts and outreach drafts by naming both and explaining the difference.

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 context on when this list is the right one (posts under the user's own name vs. comments on others' posts vs. connection notes), and it flags that 'Publishing is a separate step', routing the agent toward the approve_* siblings. It stops short of naming a fallback like list_drafts for a mixed view, so the routing 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?

With no annotations, the description carries the full burden and does well: it declares a read-only surface implicitly (drafts waiting for review, none sent), enumerates the entry fields the caller will see, and warns that approval is a distinct action requiring explicit user consent. It stops short of stating volume, ordering, or whether results are truncated.

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 prose is tightly front-loaded: what it lists, what state the items are in, what each entry contains, then the decision/approval rule. The trailing '### Responses: 200 Successful Response / Content-Type: application/json' block is HTTP boilerplate that adds no decision value for an agent.

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

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

With no annotations and no output schema, the description must convey both safety profile and return shape, and it does describe entry fields and the non-destructive nature. Gaps are minor: no guidance on ordering, result size, or how to fetch full note text once a draft handle is chosen.

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

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

The tool takes zero parameters, so there is no parameter semantics to convey and the schema can carry the full contract. The description usefully redirects that space to describing the shape of each returned entry instead.

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

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

The description gives a specific verb and a precise resource subset: connection-note drafts pending review, with the explicit clarification that nothing has been sent. That scoping distinguishes it from the other draft listings (list_reply_drafts, list_comment_drafts, list_content_drafts) without the agent having to open a schema.

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

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

It sets explicit downstream behavior — show entries to the user and let them decide — and states the approval boundary: call approve_draft only when the user explicitly asks. It does not explicitly contrast with get_draft_detail or list_scheduled, so the routing guidance covers one sibling rather than the full field.

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

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

With no annotations, the description carries the burden and does substantially more than most: it defines the exact inclusion rule ('they messaged last, not yet actioned') and gives a careful caveat on hiring_signal — badge-only, cached from a prior fetch, never a live fetch, and false means 'nothing to report' rather than a confirmed negative. That prevents a real misread. It still omits ordering, result volume, and whether results are truncated, which matter for a listing tool.

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 filter definition is front-loaded in the first sentence and the follow-up tool routing comes second, so the agent gets the gist immediately. The hiring_signal paragraph is long but earns its length by preventing a misinterpretation. The trailing '### Responses: **200**: Successful Response' block is auto-generated boilerplate that adds nothing.

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

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

With no input params and no output schema, the description must cover what comes back, and it does at a high level ('chat handles'). The hiring_signal field is explained in depth. What is missing for a listing tool is ordering, page size, and truncation behavior — an agent cannot tell how many threads to expect or whether it needs to paginate.

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?

Zero parameters, so there is nothing for the description to document and the baseline is 4. The hiring_signal explanation usefully characterizes a returned field rather than an input, which is bonus context rather than compensation.

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 ('List') and a precisely scoped resource: inbound threads where the counterparty messaged last and no action has been taken. That scoping parenthetical is what separates it from list_chats / list_reply_drafts without naming them, so an agent can reason about the difference. It stops short of explicitly contrasting with the sibling listing tools, which keeps it at 4 rather than 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?

It implies the downstream workflow well ('Returns chat handles ready for draft_reply / get_thread / schedule_chat_reply'), so the agent knows what to do next with results. However, it never says when NOT to use this tool or names the alternative (e.g. list_chats for the full inbox, find_stale_threads for aging threads). Usage is inferable but not differentiated.

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

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

No annotations are supplied, so the description carries the burden. It does disclose a meaningful behavioral trait beyond the name: only pending drafts are returned, not all drafts. However, it says nothing about ordering, pagination, or volume, and the trailing '### Responses: 200' block is raw HTTP boilerplate that adds no behavioral information.

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 useful content is two short sentences and is front-loaded, which is good. But the '### Responses: **200**: Successful Response / Content-Type: application/json' section is pure API documentation noise that wastes the reader's attention without earning 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 zero-parameter read tool with no output schema, the description covers what it lists and the scope (pending), but leaves gaps: no indication of the fields a draft contains, ordering, or how the result feeds the approve/skip/rewrite siblings.

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 and the schema is empty, so there is no parameter semantics to explain; the baseline of 4 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 ('List Reply Drafts') and narrows scope to 'pending inbound-reply drafts awaiting your review.' That is clear enough to act on, but it never distinguishes this from the many similar siblings such as list_drafts, list_replies, list_comment_drafts, and list_content_drafts, so an agent must guess which list to call.

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 phrase 'awaiting your review' implies this is the queue of drafts that still need a decision (presumably feeding approve_reply_draft/skip_reply_draft/rewrite_reply_draft), but no explicit when-to-use, when-not-to-use, or alternative tool is named.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the key behavioral trait that listed items are live and will send unless cancelled, and that each carries a send time. It does not cover ordering, whether past sends are included, pagination, or any read-only confirmation.

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, front-loaded sentences that state scope first, then consequence, then alternatives. The trailing '### Responses: 200 Successful Response' block is boilerplate that earns no place but does little harm.

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

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

For a zero-parameter read tool with no output schema and no annotations, the description is nearly sufficient: it says what is listed and that each entry includes a send time. It could say more about the shape of each entry or whether results are bounded, but an agent can call it correctly as written.

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 is the baseline-4 case; there is nothing for the description to disambiguate. The schema description coverage is 100% and the input object is empty, so no parameter explanation is owed.

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 ('List Scheduled') and defines the scope precisely: 'Everything approved and queued to send, with the time each one goes out.' This implicitly separates it from list_drafts (unapproved) and list_replies, but never names those siblings explicitly, so the differentiation is left to inference.

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 reschedule_send to move an item and cancel_scheduled to stop it. Adds the important condition 'WILL send unless cancelled'. What's missing is guidance on when to call this versus list_drafts or list_replies to find a queued item.

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

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

With no annotations, the description carries the full behavioral burden and meets it: it discloses that data is read live from LinkedIn, budgeted to a few times a day, and that LinkedIn only retains pending requests. It also explains return fields, the `handle` presence/withdrawal constraint, `total` semantics, and the `complete: false` >500 caveat.

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 with purpose and usage, then behavior and exclusions. It is somewhat long, especially the synonym list, but most sentences add real value for a tool with no annotations or output schema. A little trimming of the synonym block would improve it.

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

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

Given no annotations, no output schema, and only two optional parameters, the description is complete enough for correct invocation. It covers purpose, usage, alternatives, behavioral constraints, return values, edge cases, and parameter semantics, leaving no material gap for an agent.

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 0%, so the description must compensate. It explains that `limit` is how many to return (default 100) and that `order` selects newest or oldest first, including the practical purpose of `order=oldest` for finding the stalest. The 500 maximum is only implied through the `complete: false` caveat rather than stated as a parameter constraint.

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 first sentence states a specific verb and resource: 'List the user's SENT connection requests that are still pending.' It immediately distinguishes this from received requests (list_connection_requests) and queued requests (list_scheduled), so an agent can select it without opening sibling schemas.

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

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

The description gives explicit when-to-use phrases ('show/list my sent requests', 'who hasn't accepted', 'oldest pending') and an explicit do-not-use clause for received or scheduled requests. Alternatives are named directly, leaving no inference needed.

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

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

With no annotations present, the description carries the full burden and mostly does: it declares the operation read-only and side-effect free ('nothing is sent or changed'), states the sort order (newest first), and names the returned fields. It does not mention result size limits or pagination, which is the only remaining gap for a list operation.

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?

Strong front-loading: purpose first, then use/do-not-use in caps-labelled blocks. Minor waste from the leading title restatement ('List Solved Issues') and the trailing HTTP '### Responses: **200**' boilerplate that adds nothing for an agent.

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

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

For a zero-parameter read tool with no output schema, the description supplies everything an agent needs: ordering, returned fields, side-effect profile, and routing to siblings. There is no meaningful missing information.

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 no parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description also correctly implies no filtering arguments are accepted.

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

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

Specific verb+resource plus a precise scope: 'Known problems the Iridium team has already fixed, newest first.' It is clearly separated from list_tools (capabilities) and report_issue (filing new bugs), so an agent can pick 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 both a proactive trigger ('USE THIS before report_issue, to check whether the thing you just hit is already solved') and a reactive one ('when a user asks whether a problem they remember has been fixed'). It also names an explicit exclusion and the correct alternative ('DO NOT USE as general help or documentation... Call list_tools for that').

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

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

With no annotations provided, the description carries the burden and mostly does: it discloses that results are account-scoped and permission-filtered, that absence means the tool is disabled rather than nonexistent, and that responses are 200/JSON. It does not state read-only/no-side-effects explicitly or whether the list is cached, so one behavioral trait is left implicit.

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

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

The core content is front-loaded and tight: purpose, trigger, constraint, and return anatomy in three short sentences. The trailing '### Responses: 200 ... Content-Type: application/json' block is boilerplate from the spec dump and earns no place in the description.

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

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

There is no output schema, no annotations, and no parameters, yet the description still explains the two return fields (capabilities and tools), the filtering semantics, and how to use each field. Nothing an agent needs to call this correctly and interpret it is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly adds no parameter noise.

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 ('List Tools') and immediately narrows the scope: the Iridium tools available to this account, filtered by what the user has enabled. It is unmistakably a discovery/meta tool, which cleanly separates it from all 60+ action siblings like run_outreach_pipeline or list_drafts.

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 trigger ('answering "what can you do?" without guessing') and an explicit negative rule with a consequence: 'A tool absent from this list is switched off for this account, so do not offer it.' It also tells the agent which return field to use for which task (capabilities for user-facing answers, tools for picking the call).

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

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

No annotations are provided, so the description carries the full burden and does it: it declares the anonymity policy, that nothing is sent to LinkedIn, that no account state changes, that nobody replies, that the report cannot be followed up, the exact return payload, and the 422 rejection behavior with guidance on how to recover. This is far beyond what a bare mutation flag would 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?

Front-loaded with purpose, then return contract, then use/don't-use, then arg guidance, then the privacy rule — a logical order an agent can scan. It is long and a few points repeat (the no-identifiers rule appears in the args block and again in the NEVER paragraph, and again in the schema), but every section earns its place given the privacy gate is a hard failure mode.

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 four-required-parameter write-ish tool with no annotations and no output schema, the description supplies the return value, the failure mode (422), the privacy contract, the sibling pre-check, and the routing rules. Nothing an agent needs in order to call this correctly or avoid calling it wrongly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value the schema does not: the meaning of the three importance levels, the 200-character limit restated, a concrete worked example of an acceptable report vs. an unacceptable one, and the enumeration of forbidden identifier types (names, companies, @handles, draft_/chat_/prof_ prefixes). Only the frequency enum gets no extra gloss beyond what the schema already says.

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

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

States a specific verb and resource ('send the Iridium team an anonymous note about something that broke') and immediately distinguishes it from the two things it could be confused with: a support ticket and a LinkedIn-side action. An agent can tell from the first paragraph exactly what this tool does and does not accomplish.

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 USE THIS / DO NOT USE blocks with concrete triggering conditions ('tool failed, returned something wrong, or made a workflow the user cares about impossible to finish') and named exclusions (cap reached, LinkedIn disconnected, draft skipped — tell them instead). It also names the sibling list_solved_issues as a mandatory pre-check and gives the decision rule for what to do with its result.

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

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

With no annotations, the description carries the burden and usefully discloses the key side effect that the send will actually go out because it has already been approved, and that send_at="now" sends immediately. It still omits permission requirements and error behavior, so it is not fully transparent.

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

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

It is short and front-loaded: the core action and side effect appear before argument details, with no unnecessary filler beyond the response label.

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

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

For a simple two-parameter mutation, it covers purpose, both parameters, the key side effect, and success response. It lacks error cases and detailed return information, but 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?

Schema description coverage is 0%, so the description must compensate; it defines both required parameters, including where the handle comes from and that send_at accepts "now" or ISO-8601 with an example.

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 action and resource: rescheduling a pending send to a different time. This clearly differentiates it from siblings like list_scheduled, cancel_scheduled, and approve_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?

It implies usage for an already approved pending send and points to list_scheduled or approve_draft as handle sources, but it does not explicitly say when to use cancel_scheduled or the schedule_* tools instead, nor when not to use this tool.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that actions are queued and processed in the background, spaced out under a daily limit, that the user gets one email on completion, and that the operation cannot be undone. It also flags a semantic trap ('ignore' means decline, there is no separate ignore action).

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

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

The core instruction is front-loaded in the first two sentences and every block carries real information (prerequisites, group procedure, queuing/irreversibility, exclusions). It is somewhat long and repeats the 'call list_connection_requests first' guidance in two separate paragraphs, which costs a point.

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

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

For a two-param, no-annotation, no-output-schema mutation tool, the definition covers everything an agent needs: prerequisites, decision authority, per-person iteration for groups, the ambiguous-case fallback, async completion feedback, irreversibility, and the sibling operations it is not. Only the 200-only response shape 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 coverage is 0%, so the description must compensate, and it does for the key ambiguity: it tells the agent the `handle` comes from list_connection_requests, and that `action` is accept or decline, mapping user synonyms (approve/add/connect, reject/ignore/dismiss) onto the two enum values. It stops short of describing handle format or validation.

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 (respond: accept or decline) and a specific resource (one received connection request), and immediately scopes it to ONE request, which distinguishes it from list_connection_requests and from withdraw_connection_request named at the end. The agent can tell exactly what operation this performs without reading 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 explicit preconditions (must call list_connection_requests first, must have a user decision naming who), explicit exclusions (never act on own initiative, not for sending/withdrawing own requests or replying to messages), and a procedure for the ambiguous group case (skip unclear ones, finish the rest, then ask). Alternatives are named outright.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the operation is asynchronous and runs in the background, and that it does not publish. It does not say whether the rewrite overwrites the existing draft text in place (i.e. whether the handle stays valid and the old text is lost), which is the main remaining behavioral uncertainty.

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

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

The core content is front-loaded and the async warning is correctly placed before the Args block. The trailing '### Responses: **200**' HTTP boilerplate adds no information for an agent and slightly dilutes the text.

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

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

No annotations and no output schema, so the description must do the work, and it does: async behavior, follow-up read step, and both parameters are covered. The gap is what the eventual read-back looks like and whether the draft handle remains the same after rewriting.

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 0%, yet the description documents both parameters: handle is typed as a 'cdft_ handle from list_comment_drafts' (source and format), and instruction is explained with concrete examples plus the semantics of omitting it. This fully compensates for the empty 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 ('Rewrite a comment draft') and adds a key boundary: 'Does not post.' This distinguishes it from approve_* and run_commenting_pipeline. It does not, however, differentiate itself from the close sibling edit_comment_draft, which an agent could easily confuse with rewriting.

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 follow-up procedure ('call list_comment_drafts afterwards to read the new text') and a default rule for the optional parameter ('Omit for a general retry'). It lacks an explicit when-not rule, e.g. when to choose edit_comment_draft instead of a rewrite.

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

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

With no annotations, the description carries the full disclosure burden. It usefully discloses that the rewrite is asynchronous, does not publish, and requires a follow-up list_content_drafts call, but it does not describe permissions, error behavior, or what the immediate response contains.

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

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

The core behavior and follow-up step are front-loaded and easy to scan. There is minor waste from repeating the title and including boilerplate HTTP 200 response text, but the useful content is not 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?

Given no output schema and no annotations, the description provides enough context to call the tool correctly: what it does, how to obtain the handle, examples for the instruction, and how to retrieve the resulting text. It leaves some operational details undocumented, but the async workflow is covered.

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 0%, so the description has to compensate. It does so for both parameters by explaining that handle is a ctnt_ handle from list_content_drafts and giving examples of what instruction means, although it does not clarify that instruction is optional in the schema.

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

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

The description states a specific verb and resource: "Rewrite a post draft with an instruction." The ctnt_ handle reference links it to content drafts and helps distinguish it from reply/comment draft tools, though it does not explicitly contrast it with the generic rewrite_draft sibling.

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 usage context: this rewrites rather than publishes, and the rewrite runs in the background so the agent should call list_content_drafts afterward to read the result. It does not explicitly say when to choose rewrite_draft versus rewrite_content_draft, so it stops short of full alternative 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?

With no annotations provided, the description carries the behavioral burden and does well: it discloses that the operation is non-sending, that it executes in the background, and that the new text will NOT be in the response — the single most important fact for correct orchestration. It omits permission requirements, whether repeated calls compound changes, and failure behavior, which keeps it short of 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?

Front-loaded with purpose, then the critical async caveat, then per-argument notes — good ordering with no wasted prose in the body. The trailing "### Responses: **200**: Successful Response ... Content-Type: application/json" block is HTTP boilerplate that adds nothing for an agent and slightly dilutes the signal.

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

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

For a two-parameter, no-output-schema, no-annotation tool, the definition covers the essentials: what it mutates, that it does not send, and exactly how to retrieve the result. Remaining gaps are secondary — whether the rewrite overwrites the existing draft in place, and whether re-invoking stacks changes.

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 0%, so the description must compensate, and it does: it identifies the 'draft_' handle prefix and its provenance (list_drafts), and characterizes the instruction semantically with three concrete examples of the expected free-form style. That is meaningfully more than the bare string types in the schema.

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

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

States a specific verb and resource — "Rewrite a connection-note draft with an instruction" — and immediately bounds the outcome with "Does not send." The phrase "connection-note draft" distinguishes it from the sibling rewrite_reply_draft, rewrite_comment_draft, and rewrite_content_draft without the agent needing to open their schemas.

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

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

It gives clear operational context: the rewrite is asynchronous, so the caller must follow up with get_draft_detail or list_drafts, and the handle is sourced from list_drafts. It does not explicitly say when to prefer this over edit_comment_draft-style manual editing or when to pick the sibling rewrite_* tools, but the resource scoping makes the choice largely self-evident.

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

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

With no annotations, the description carries the full burden and does disclose one important trait: it does not send, so no external side effect occurs. It does not say whether the rewrite replaces the existing draft text in place or creates a new version, whether the original is recoverable, or whether approval is still required afterwards.

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

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

The core sentence is tight and front-loaded, and the instruction example earns its place. The trailing '### Responses: **200**: Successful Response (Success Response) Content-Type: application/json' block is boilerplate that tells an agent nothing actionable and dilutes the definition.

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

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

There is no output schema and no annotations, and one of the two required parameters is undefined, yet the description never says what comes back (rewritten text? a draft object? an ID) or what a handle is. For a two-required-parameter mutation tool with zero structured support, this leaves too much to guesswork.

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 0%, so the description must compensate. The instruction parameter is genuinely illuminated by the 'shorter' / 'propose Tuesday' examples, which show it is a free-text directive rather than a keyword. The 'handle' parameter gets no explanation at all, leaving it unclear whether it identifies a draft, a thread, or a person.

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: 'Rewrite a reply draft with an instruction', and gives concrete instruction examples ('shorter', 'propose Tuesday'). The resource name itself ('reply draft') separates it from rewrite_draft, rewrite_comment_draft and rewrite_content_draft in the sibling list, though the description never makes that distinction explicit.

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?

'Does not send' implies this is a safe pre-send editing step, which hints at where it sits relative to draft_reply and approve_reply_draft. However, it never states when to rewrite versus re-draft or edit, nor any precondition such as the draft needing to exist in a particular state.

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

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

With no annotations, the description carries the full burden and does well: it discloses the 3-draft cap, that search spans all of LinkedIn, that it draws on saved comment_topics, that the caller must display every draft in full, and that nothing is approved or scheduled automatically. It stops short of saying whether the drafts persist and become visible to list_comment_drafts, or what happens when no relevant posts are found.

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 a labeled use/do-not-use block, then post-call output instructions — a clean hierarchy. The mandated display template is somewhat verbose and the appended HTTP response boilerplate adds little, but nearly every line changes agent behavior.

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

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

There is no output schema, and the description compensates by naming the returned fields (author_name, post_text, comment_text) and prescribing exactly how to render them. For a zero-parameter, no-annotation tool, an agent has everything it needs to call it and act on the result.

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 is the baseline 4 case; there is nothing for the description to disambiguate. Its implicit note that topics come from the user's saved comment_topics usefully explains where the input actually comes from, given the empty 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 ('Generate up to 3 LinkedIn comment drafts on relevant posts') plus the mechanism ('searching all of LinkedIn for the user's saved comment_topics'). It explicitly distinguishes itself from run_company_commenting_pipeline and, by scope, from search_posts_by_topic.

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 an explicit USE THIS block with three realistic utterances, plus a DO NOT USE rule naming the situation (user names specific companies) and the correct alternative tool. Nothing about tool selection 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?

No annotations are provided, so the description carries the full burden and does so well: it explains the no-keyword-filter design, that zero drafts is a valid outcome not an error, that unresolved_companies should be surfaced, that n is capped by the user's daily cap, and that the model judges topical relevance. It also specifies the required post-call behavior of displaying every draft in full.

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 a clear USE/DO NOT USE structure. The long output-format template and follow-up instructions are useful but make it longer than a typical tool description; still, nearly every sentence serves a distinct behavioral or routing purpose.

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

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

Complete for a multi-parameter pipeline tool with no annotations and no output schema. It covers routing, parameter semantics, failure modes, empty-result handling, caps, and required post-call display behavior, leaving little an agent would need to infer.

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 0%, but the Args section documents all three parameters: companies with a max of 5, n with default 3 and daily-cap behavior, and date_posted with the allowed values and default. This adds essential meaning beyond the bare schema, which has no descriptions or enums.

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: generate LinkedIn comment drafts on recent posts by employees of named companies. It explicitly distinguishes from the sibling run_commenting_pipeline by explaining this tool searches by AUTHOR COMPANY and recency, not keywords.

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 trigger examples ('comment on posts from people at Stripe') and an explicit DO NOT USE case with examples, naming run_commenting_pipeline as the alternative for topic/keyword commenting. Also states not to approve or schedule unless asked.

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

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

With no annotations, the description carries the full behavioral burden and does so well. It discloses that the tool runs in the background and returns immediately, publishes nothing, requires content topics, reads results elsewhere, and returns a skipped status with reason on a same-day second call.

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 important constraints are front-loaded and easy to scan. There is minor waste in the repeated title line and the boilerplate Responses/Content-Type section, but the description is still compact and purposeful.

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

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

For a zero-parameter asynchronous tool with no output schema and no annotations, the description supplies everything an agent needs: purpose, non-publishing behavior, asynchronous result retrieval, prerequisite, rate limit, and skipped-status behavior.

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

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

The tool has zero parameters, so parameter semantics are effectively moot and the schema is empty. The baseline for a zero-parameter tool is 4.

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: drafting LinkedIn posts from saved content topics and voice. It also distinguishes the output from publishing ('Produces drafts only and publishes nothing') and routes result-reading to list_content_drafts, so the agent can identify the tool's role 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?

It gives clear operating context: saved content topics are required, results are read via list_content_drafts, and the pipeline runs at most once per day. It does not explicitly enumerate when to choose this over run_outreach_pipeline or run_commenting_pipeline, but the content-specific framing makes the intended use 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?

With no annotations, the description carries the full burden and does well: it discloses that output is drafts only and nothing is sent (safe/non-destructive), gives expected latency (~5 seconds), fixes the output cardinality at 3, and specifies inline return. It omits prerequisites such as whether LinkedIn credentials must be connected and what happens when no saved targets exist.

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

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

The core behavior is front-loaded in a single strong first sentence, and the display template and do-not-chase constraints are actionable. The trailing '### Responses: **200**: Successful Response / Content-Type: application/json' block is raw OpenAPI boilerplate that adds no decision value.

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

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

With no output schema and no annotations, the description compensates well by fully specifying the returned draft fields and the required presentation format, so an agent knows exactly what to show. The remaining gaps are prerequisites (connected LinkedIn account) and failure/empty-target behavior, which matter for a pipeline 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?

Zero-parameter tool, so the baseline is 4; there is nothing for the description to disambiguate. The only missed opportunity is noting that targets are configured elsewhere rather than passed as arguments.

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+cardinality: 'Draft 3 connection notes against the user's saved targets and return them inline in about 5 seconds.' 'Connection notes' implicitly separates it from run_commenting_pipeline and run_content_pipeline, but no sibling is named explicitly, so the differentiation is inferred rather than stated.

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 a clear when-not for follow-up tools ('Do NOT call approve_draft or schedule anything unless the user explicitly asks'), which is useful routing guidance. However, it never says when to pick this tool over discover_prospects, find_prospects, or draft_reply, nor how 'saved targets' are populated, so selection guidance is only partial.

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

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

With no annotations, the description carries the burden and does the important part: it flags the operation as a real send, discloses the connection-limit side effect, and imposes an approval precondition. It omits other behavioral facts an agent would want — idempotency, what happens if send_at is in the past, and whether the scheduled message can later be altered via reschedule_send or cancel_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?

Front-loaded with the purpose and the 'THIS SENDS' warning before any argument detail, then a tight Args block. The trailing '### Responses: 200 Successful Response / Content-Type: application/json' is boilerplate that conveys nothing actionable and could be dropped.

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

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

Given no annotations and no output schema, the description covers purpose, side effects, preconditions, and every parameter. The remaining gap is return behavior: with siblings like cancel_scheduled and reschedule_send, the agent would benefit from knowing whether a handle or job id comes back.

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 0%, so the description must compensate and it does: chat_handle is documented with its source tools (list_chats or search_chats), text is pinned to 'the exact message to send', and send_at is given accepted forms ('now', ISO-8601 with offset, or omit for immediate). All three parameters are meaningfully specified.

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

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

States a specific verb (send or schedule) and resource (a message into an existing conversation), plus the emphatic 'THIS SENDS' marker so the agent knows the operation's effect. The 'existing thread' framing implicitly separates it from the new-connection DM siblings 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?

Gives a clear selection rule ('only when the user has approved this specific message') and a useful non-obvious fact — it creates no new connection and does not count against the daily connection limit. It does not, however, name the sibling alternatives (schedule_manual_dm, schedule_dm_to_person, draft_reply) that an agent should consider first.

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

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

With no annotations at all, the description carries the full burden and does well: it discloses that the message routes into an existing thread, else becomes a DM, else a connection-request note, and that batched messages are spaced out to avoid a burst with the reply reporting moves. It stops short of covering auth/permission requirements, reversibility, or how to undo a scheduled send (cancel_scheduled exists but is not mentioned).

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

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

Front-loaded with the action and the workflow before the argument list, and every section is scannable. It runs long and repeats the send semantics in both the 'THIS SENDS' line and the routing paragraph, but that repetition is defensible for a high-stakes mutation.

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

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

For a 5-param mutation with no annotations and no output schema, the definition covers routing, prerequisites, batching behavior, and all argument semantics. What it lacks is any statement of what the 200 response contains beyond 'the reply says so when a message is moved', and no mention of failure modes or permissions.

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 0%, so the description must compensate, and it does: profile_handle is defined as the prof_ handle from find_person/get_linkedin_profile (never a name), text as the exact message, send_at as "now" or ISO-8601 with offset, name as an optional queue label read from the profile when omitted, and message_type with its three concrete values.

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

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

States a specific verb+resource ('Send or schedule a direct message to a person') and immediately distinguishes itself from the lookup tools that precede it (find_person, get_linkedin_profile) and from the chat-based sibling schedule_manual_dm. The 'THIS SENDS' line makes the state-changing nature unmistakable.

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

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

Gives an explicit ordered workflow (find_person → get_linkedin_profile → schedule_dm_to_person) with conditions for each step, plus a clear exclusion: if already in a thread, use schedule_manual_dm with the chat_ handle instead. It also states a precondition (verdict must be `confirmed`, otherwise ask the user).

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

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

No annotations exist, so the description carries the burden; it discloses the send_at="now" vs ISO-8601 semantics and the direct_message/inmail choice. It omits what happens on failed scheduling, whether scheduled messages can be cancelled/edited (see cancel_scheduled, reschedule_send), auth requirements, and any rate limits.

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

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

The Args block is efficient and front-loads the useful constraint, but the definition wastes space repeating the title ("Schedule Manual Dm") and appending boilerplate HTTP response text ("### Responses: **200**... Content-Type: application/json") that adds nothing for tool selection.

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

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

With no output schema and no annotations, more is expected; the description covers inputs and the scheduling concept but says nothing about the return value (job id? message id?) or how the scheduled item relates to cancel_scheduled/list_scheduled. Adequate but with clear gaps.

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 0%, so the description must compensate, and it does: all four parameters are explained, including accepted values for send_at and message_type. It falls short of a 5 only in not stating format constraints such as timezone handling or text length limits.

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 a meaningful constraint ("a direct message to someone you're already connected with"). However, it never distinguishes itself from close siblings like schedule_dm_to_person or schedule_chat_reply, which an agent must choose between.

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 one concrete prerequisite step ("Use list_chats to find the chat_handle") and an implicit connection requirement. It offers no guidance on when to pick this over schedule_dm_to_person, schedule_chat_reply, or reschedule_send.

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

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

With no annotations, the description carries the full burden and does disclose a genuinely useful behavioral trait: execution is local with no LinkedIn quota cost. It also states the return shape at a high level ('chat handles ready for get_thread / schedule_chat_reply'). It omits pagination/limit behavior and any auth or read-only framing, which keeps it from 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?

Front-loaded with purpose and cost profile, then the operator list, then the return value — a sensible order with little wasted prose. The trailing '### Responses: 200 ... Content-Type: application/json' boilerplate adds no informational value and could be dropped.

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 10-parameter tool with no annotations and no output schema, the description covers the query grammar, the local-execution property, and what comes back, which is most of what an agent needs. Missing are result-shape detail beyond 'chat handles', how limit interacts with paging, and any notion of result ordering.

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 0%, so the description must compensate, and it largely does: it enumerates the operator vocabulary (is:unread/read, from:, company:, after:/before:, newer:/older:) and maps it onto the discrete args. `limit` is the one parameter with no explanation of its default of 50 or its effect on result volume, leaving a gap.

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 your LinkedIn inbox') plus the two search modes: free-text content matching and structured filters. The scope note ('all local, no LinkedIn quota') and the example query 'who mentioned CMU' make the semantics concrete. It does not explicitly name the nearest sibling (list_chats) to contrast with, so it stops short of a 5.

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

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

Gives clear guidance on how to filter (free text vs. operators) and shows both invocation styles ('in `q` or as discrete args'), plus a worked example. It implicitly routes the agent to get_thread / schedule_chat_reply for follow-up, but never states when NOT to use it or names an alternative tool such as list_chats.

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

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

With no annotations, the description carries the full burden and does so well: it declares reads-only, no drafts, no profile opens, an explicit cost model ('the cost is the same whether it returns 1 post or 50'), ordering (newest first), and that reposts are dropped. It omits any statement about auth/permission prerequisites or rate limits, which keeps it off 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?

Well front-loaded and sectioned (scope → USE → DO NOT USE → Args → Returns), so an agent can scan it quickly. Minor waste: the title is restated verbatim at the top, and the '#hiring post vs profile badge' distinction is made twice, though the repetition is defensible given the stakes.

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 six-parameter tool with no annotations and no output schema, the description supplies everything needed: full parameter semantics, the return shape ({posts, count, has_more} with per-post fields), and a hand-off hint that prof_ handles feed get_linkedin_profile or schedule_dm_to_person. Nothing an agent needs to call or chain this tool 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?

Despite 0% schema description coverage, every one of the six parameters is explained with meaning beyond the schema: keywords is post-body text (and hashtag-in-post ≠ profile badge), author_company and author_keywords are author-side filters, date_posted enumerates values with default and sort order, posted_by defines the network scope, and limit gives range, default, and the repost-dropping behavior.

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

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

States a specific verb and resource ('Search LinkedIn posts by topic') plus the exact output contract: each post returned with its author as a candidate. The second paragraph makes the distinction from people-search siblings (search_prospects, find_prospects) unmistakable.

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

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

Explicit 'USE THIS when' with three concrete query examples, plus a 'DO NOT USE' clause naming the alternatives (search_prospects / find_prospects for topic-less people search, discover_prospects for message writing). It even resolves the subtle case of posted-about-hiring vs profile #hiring badge, which is exactly where an agent would otherwise pick the wrong tool.

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

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

With no annotations, the description carries the full burden and does so: declares 'Reads only, drafts nothing', quantifies cost (ONE LinkedIn action, zero profile touches), discloses that results are read live at call time, and explains that hiring_only/open_to_work_only reorder rather than filter — including the prior buggy behavior. It also flags that posted_recently and open_to_work require Sales Navigator / full Recruiter seats and degrade gracefully with a `tier_note`.

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 — cost and read-only nature appear in the first two lines, and the USE/DO NOT USE blocks are easy to scan. But the 'the badge lives only on the full profile' point is restated at least four times across the header and Args section, inflating a definition that could be a third shorter without losing meaning.

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

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

No annotations and no output schema, yet the description covers safety, cost, tier gating, the sort-not-filter semantics, and even references response fields (`note`, `tier_note`). The remaining gap is on the mechanics of the required query/location strings and the `limit` cap, which an agent must guess.

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 0% and there are 7 params, so the description has to compensate — and it explains four of them in real depth, including the crucial distinction between open_to_work (LinkedIn-confirmed spotlight) and open_to_work_only (headline-based guess). However, query, location, and limit are never described (no syntax, no format, no pagination guidance), leaving three params undocumented.

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 ('search prospects') and immediately bounds its scope: matches on query and location only, no signal filtering, no profile opens. It explicitly distinguishes itself from find_prospects (profile-confirming) and discover_prospects (search + draft), so an agent can pick 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?

Provides explicit 'USE THIS' and two 'DO NOT USE WHEN' clauses, each naming the alternative tool and the condition that selects it (badge truth → find_prospects; message drafting → discover_prospects). This is the textbook when/when-not/alternatives structure.

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