Reach MCP

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

Annotations already declare openWorldHint, idempotentHint and destructiveHint, so the safety profile is covered externally. The description adds a real behavioral instruction ("Ask the user which ones"), indicating a confirmation step, but omits rate limits or irreversible side effects on LinkedIn. There is no contradiction with annotations.

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

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

Three short sentences, front-loaded with the core action, with no padding. The parenthetical invitation_secret reference is the one sentence that damages rather than earns its place.

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

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

An output schema exists, so return values need no explanation, and annotations carry the idempotency/destructiveness profile. However, a mutation tool whose description identifies the wrong input field and never mentions the account scoping requirement is not fully complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description names "invitation_secret" as the input while the actual required parameters are account_id and linkedin_id_or_url. This mismatch points the agent at a parameter that does not exist (and additionalProperties: false would reject it), actively misleading rather than adding meaning.

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 opening sentence names a specific verb and resource ("Accept a pending received connection request"), which clearly separates it from send_invitation and withdraw_invitation. It lacks explicit sibling naming (e.g. decline_invitation), so it falls short of a 5.

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

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

It states when to use the tool and where the input originates ("invitation_secret from list_received_invitations"), which routes the agent correctly. It never states when not to use it or names decline_invitation as the alternative, so no exclusions 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?

Annotations already declare destructiveHint=false and idempotentHint=true, so the safety baseline is covered. The description adds genuinely useful context beyond them: the operation is reversible via archive=false and is housekeeping rather than deletion. It doesn't add auth or rate-limit notes, but for a low-risk reversible toggle that is reasonable.

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

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

Front-loads the core action in the first sentence, then adds only the unarchive flag, the id source, scope, and the explicit non-delete routing note. Every sentence earns its place with zero padding.

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

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

With an output schema present, return values need no explanation, and the description covers the action, direction, reversibility, ID provenance, and the delete alternative. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including archive semantics and the idempotency_key contract. The description restates archive=false and the provenance of conversation_linkedin_id but adds no syntax or format detail beyond the schema. Baseline 3 when the schema carries the load.

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 ('Archive or unarchive a LinkedIn conversation') and immediately distinguishes itself from the sibling delete_conversation. The dual-direction behavior (archive/unarchive via archive=false) is spelled out, so the agent can tell exactly what the tool does without opening 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 context ('Housekeeping in the classic inbox') and names the alternative for the delete case ('Not a delete, see delete_conversation'), plus the unarchive condition. It stops short of positioning against star_conversation, the other non-destructive conversation-state sibling, so routing is not fully exhausted.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally; the description adds the concrete consequences (pending items never run, executed items remain, cannot be undone). It does not restate the idempotency-key retry semantics, but those live in the schema description, so this is a modest gap rather than a miss.

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 operation and its consequence, and every clause is decision-relevant. Minor redundancy between 'Cannot be undone' and 'Irreversible for the pending items' costs a point, but there is no filler.

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

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

For a destructive, irreversible tool with a full output schema and complete annotations, the description supplies the consequence model and the pause_job alternative an agent needs. What is missing — post-cancellation job state and response shape — is covered by the output schema.

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

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

Schema description coverage is 100%, including job_id provenance ('as returned by create_job or list_jobs') and a full idempotency_key explanation, so the schema carries all parameter meaning. The description adds nothing about parameters, which is the correct baseline when coverage is complete.

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

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

States a specific verb+resource ('Cancel a job') and immediately clarifies scope: pending items will never run, executed items are unaffected. It explicitly contrasts with the sibling pause_job, so an agent can distinguish it from create_job/list_jobs/get_job 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?

Explicitly routes to the alternative: 'To stop temporarily use pause_job.' It also adds a when-to-use guardrail — 'confirm with the user' — for an irreversible action, which is exactly the decision context an agent needs.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the mutating/external nature is covered structurally. The description adds genuinely new context beyond the annotations: it consumes the daily comment quota and the content becomes publicly visible, which is the kind of side-effect disclosure that matters for a write tool. It stops short of explaining what happens when the quota is exhausted (e.g., pointing at get_account_quotas), so it is strong but not 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?

Three short sentences, front-loaded with the core action, then the disambiguation, then the caveats. Every sentence carries information an agent needs; no filler or restatement of the tool name.

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

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

An output schema exists so return values need not be explained, and annotations cover the safety profile. The description covers scope, alternative, quota and visibility, but omits what to do on quota exhaustion or auth failure, the only real gap for a write tool with sibling quota-inspection tools available.

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

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

Schema description coverage is 100% for all four parameters, including a detailed idempotency_key explanation, so the schema does the heavy lifting. The description adds no parameter-level detail (no format for post_url_or_urn, no note that account_id comes from list_accounts), which matches the baseline 3.

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

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

States a specific verb and resource ('Post a comment on a LinkedIn post') plus the acting principal ('on behalf of the connected account'). It explicitly distinguishes itself from the sibling reply_comment, so an agent can route correctly 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 the when ('write a new top-level comment on a post'), the when-not with the named alternative ('to answer an existing comment use reply_comment'), and operational caveats (daily quota, public text, preview with the user). Nothing about 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?

Annotations only declare the safety profile; the description goes far beyond, disclosing asynchronous execution, spreading across the account activity window with human-like gaps, quota-bounded behavior, self-pausing on quota/disconnect and self-resuming, webhook lifecycle events (job.started/progress/paused/completed), and that it returns immediately with a job_id and schedule so the agent need not stay alive.

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 is well front-loaded, but the closing sentences ('Use for any batch above a handful of actions; returns at once with the schedule. Show the items to the user first. Not for a single action, call the direct tool.') restate content already delivered earlier in the paragraph, adding length without new information.

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

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

Given an output schema exists, the description does not need to detail return values, and it still notes the job_id/schedule return and webhook reporting. Async lifecycle, quota interaction, defaults and prerequisites are all covered for a 9-parameter batching 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 coverage is already 100%, so the baseline is 3, but the description adds meaning the schema does not: it ties window_start/window_end/timezone/days to the account-level setting managed by update_account_quotas, explains the default fallback chain, and clarifies the action-to-item-fields relationship ('fields depend on the action').

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

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

States a specific verb and resource ('Queue a batch of LinkedIn actions ... that Reach executes on its own over the following hours or days') and enumerates the action types. An agent can distinguish this asynchronously-executed batching tool from the synchronous send_message/send_invitation siblings without opening any schema.

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

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

Explicitly names the alternatives ('instead of calling send_message or send_invitation in a loop'), gives a threshold ('anything above a handful of actions'), an exclusion ('Not for a single action, call the direct tool') and a workflow rule ('Always show the user the items before queuing them'). Nothing is left to inference.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, openWorld=true, and the output schema documents the return shape. The description still adds real context: the creation workflow position, that the returned identifierUrn must be handed to create_post, and that author_urn must be sourced from get_me. It does not disclose rate limits or what happens if media_urns are invalid, keeping it just below the top.

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

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

Purpose is front-loaded and the sentences are tight, but the create_post linkage is stated twice ('to pass to create_post' and 'the single URN create_post takes'), which is mild redundancy that keeps it from a 5.

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 an output schema and annotations covering the safety profile, the description still supplies everything an agent needs: prerequisites, exclusions, parameter provenance, and the downstream handoff. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by telling the agent where author_urn comes from (get it from get_me) and what media_urns semantically are, which compensates for the schema's confusing author_urn description ('Only messages from this author URN').

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 (Create) plus resource (LinkedIn multi-photo object) with the exact input (digitalmediaAsset URNs) and output (identifierUrn). It distinguishes itself from siblings by naming both the upstream (upload_media_from_url) and downstream (create_post) tools, so an agent can place it in the workflow without opening any schema.

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

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

Explicit when: 'Use after uploading two or more images with upload_media_from_url.' Explicit when-not: 'Not for one image.' It also identifies create_post as the consumer of the returned URN, covering the relevant alternatives and ordering.

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

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

Adds real context beyond annotations: posts count against a daily quota, and the agent should show the user the full text before calling. Annotations only supply the safety profile (readOnly=false, destructive=false, openWorld=true). The idempotency behavior is left to the schema rather than restated here.

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 dense with useful detail. Slightly redundant: the schedule/omit behavior is stated twice ('Set scheduled_at … omit it to publish immediately' then 'Publishes now or schedules'), and the stray 'scheduled_time' term adds noise.

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

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

With an output schema present and annotations covering the safety profile, the description is nearly complete: it covers modes, media routing, quota, and a user-confirmation guardrail. The inconsistent 'scheduled_time' reference is the only notable gap for an agent parsing the scheduling parameter.

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

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

Schema coverage is 100% (baseline 3), but the description adds genuine value by mapping media_urn to the correct URN format per case and restating the scheduled_at scheduling semantics. Minor confusion: it later refers to 'scheduled_time', a name not present 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+resource ('Create or schedule a LinkedIn post') and immediately delineates the two modes. Distinguishes itself from siblings like create_multi_photo (referenced for the multi-image URN) and update_scheduled_post.

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

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

Gives explicit conditions: single image → digitalmediaAsset URN, multiple images → fsd_multiPhoto URN from create_multi_photo, set scheduled_at to schedule, omit to publish now. Routes the agent to the correct sibling and states the alternative publishing modes.

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

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

Annotations only cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds critical context they cannot: the signing secret is returned ONCE, the exact signature header format and HMAC construction, the default scoping of account_ids, and the https-only constraint. This is exactly the value-add the description should provide.

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

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

Dense but front-loaded: purpose first, then the secret/signature contract, then event vocabulary, then usage conditions and the exclusion. Every clause carries information. It is one long paragraph, so a reader must parse carefully, but there is no filler or repetition.

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

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

With an output schema present the description needn't enumerate return fields, yet it still flags the one-time secret exposure that matters most for correct client handling. Combined with the event list, scoping default, and routing guidance, an agent has everything needed to select and invoke the tool correctly against its 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?

Schema coverage is 100%, so baseline would be 3, but the description adds real meaning the schema lacks: it enumerates the concrete event names (message.received, connection.new, account.status_changed, quota.threshold_reached, quota.reached, '*'), which the schema leaves as an opaque string array with no enum, and it clarifies the account_ids default (omit = all accounts). It does not restate the url or idempotency_key semantics, which the schema already covers well.

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

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

The first sentence states a specific verb+resource ("Register a URL to be called when something happens on LinkedIn") and immediately frames the outcome (react instead of polling). It is clearly distinct from the sibling delete/update/list/test_webhook_endpoint tools, which share the resource but differ in verb.

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

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

Explicit when-to-use ("Use when the user wants to react to a reply, a new connection, a quota alert or a job event from n8n, Make or their own code"), a prerequisite ("needs an https URL they control"), and an exclusion ("Not for the model to call itself"). Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds a meaningful behavioral fact not in the annotations: the sender is not notified. It stops short of describing reversibility or quota effects, so not a full 5.

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

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

Three short sentences, front-loaded with the core action, then usage, then the exclusion and alternative — no filler.

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

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

An output schema exists so return values need not be explained, and the description covers action, scope, notification behavior, and the sibling alternative. Minor gap: it doesn't clarify whether the request is removed vs merely hidden from listing.

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 account_id, linkedin_id_or_url, and idempotency_key are already fully documented in the schema. The description adds no parameter-level detail, which is the baseline expectation at full coverage.

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 (decline/ignore a pending received connection request) and explicitly scopes it to received invitations, distinguishing it from accept_invitation, send_invitation, and withdraw_invitation.

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

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

Explicitly says when to use it (to ignore a received invitation) and when not to (invitations the account sent), routing the agent to withdraw_invitation by name.

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

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

Beyond the annotations (destructiveHint, idempotentHint, readOnlyHint=false), the description discloses real behavioral consequences: it clears invitation references before deletion, permanently removes only the Reach-side record while leaving LinkedIn untouched, and is irreversible. The confirmation requirement is also a meaningful operational constraint not captured by the structured fields.

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

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

Three tight sentences, front-loaded with the action and scope, then the side effect, then the exclusions and safety requirement. Every sentence carries decision-relevant information and nothing is padded.

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

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

With an output schema present, return values need not be described, and the annotations already cover safety/idempotency hints. The description supplies the remaining critical context - Reach-only scope, irreversible destruction, invitation-reference cleanup, confirmation requirement, and the temporary-disconnect exclusion - so an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, and the schema itself thoroughly documents account_id and idempotency_key, so the baseline score is 3. The description only repeats 'by account_id' and adds no format, source, or idempotency-key guidance beyond what the schema already provides.

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

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

The description states a specific verb and resource ('Delete a LinkedIn account') and immediately bounds it with 'Removes the account from Reach only (LinkedIn is untouched).' This scope distinction, plus the explicit 'Not for disconnecting temporarily,' lets an agent separate this from read/list siblings like list_accounts and from any temporary-disconnect behavior 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 a clear negative condition ('Not for disconnecting temporarily') and a prerequisite ('requires the user's explicit confirmation'), which tells the agent when not to call it and what must happen first. It stops short of naming a specific alternative tool, but no sibling tool fills that role, so the guidance is clear without an explicit routing target.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds important context beyond the annotations by stating the deletion is permanent and 'Irreversible for this account,' and by advising user confirmation. It does not cover authentication or rate-limit behavior, but that is a minor gap given the annotation coverage.

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

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

Three sentences, front-loaded with the destructive action and followed by parameter provenance, irreversibility warning, and the safer alternative. Every sentence earns its place.

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

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

Given that annotations carry safety hints and an output schema exists, the description supplies the remaining decision-critical context: permanence, irreversibility, confirmation advice, and a clear sibling alternative. Nothing an agent needs in order to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so all parameters are already documented structurally, including the detailed idempotency_key semantics. The description only reiterates that conversation_linkedin_id is returned by list_conversations, which mostly duplicates the schema rather than adding new syntax or constraints.

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

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

The description gives a specific verb and resource: 'Permanently delete a LinkedIn conversation.' It also distinguishes this tool from its sibling archive_conversation, so an agent can identify it 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 explicitly names the alternative and the condition for choosing it: 'To hide a thread without losing it use archive_conversation.' It also tells the agent to confirm with the user before calling, which gives clear usage guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the key operational context the annotations cannot: the action is irreversible and requires user confirmation, and the target scope is limited to still-scheduled posts. That is exactly the 'what gets destroyed / preconditions' context the rubric rewards.

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

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

Three tightly packed sentences: identity first, then parameter provenance, then scope and safety constraints. No filler and every clause carries actionable 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 destructive single-target delete with a full input schema, an output schema, and complete annotations, the description covers everything the agent needs: the target, its source, the exclusion of published posts, and the confirmation/irreversibility requirement.

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 post_urn, account_id and idempotency_key are already fully documented in the schema. The description restates post_urn's origin (list_scheduled_posts) and gives an example URN shape, which is mildly useful but largely duplicates the schema, so the baseline 3 applies.

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

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

States a specific verb (delete) and resource (scheduled LinkedIn post), and scopes it to scheduled rather than published posts, which distinguishes it from the sibling update_scheduled_post and list_scheduled_posts. An agent can tell exactly what this 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?

Gives explicit when (posts still scheduled, URN sourced from list_scheduled_posts) and when-not (a published post cannot be deleted through Reach), plus a workflow prerequisite to confirm with the user. Nothing about routing to this tool versus its siblings is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still adds meaningful context beyond them: the operation is irreversible and specifically destroys the delivery history, plus it mandates user confirmation before proceeding — exactly the 'what gets destroyed' detail the rubric rewards.

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

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

Three short clauses, front-loaded with the destructive action and its scope, then the irreversible/confirm caveat, then the alternative. Every sentence earns its place with no filler.

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

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

Output schema exists so return values need no explanation, and annotations already cover the safety/idempotency profile. The description supplies the remaining critical facts — irreversibility, scope of deletion, confirmation requirement, and the pause alternative — leaving nothing an agent needs missing.

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

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

Schema description coverage is 100% and both parameters (endpoint_id, idempotency_key) are fully documented in the schema, including the idempotency retry semantics. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

Specific verb+resource ("Delete a webhook endpoint") immediately says what happens, and it further names the secondary effect ("and its delivery history"). It also routes the agent away from destructive intent when pausing is the actual goal, distinguishing it from siblings like update_webhook_endpoint.

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

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

Explicit when-to-use (removing an endpoint and its history), explicit when-not-to-use with the exact alternative ("To pause deliveries use update_webhook_endpoint with is_active=false"), and a required precondition ("confirm with the user"). Nothing is left to inference.

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

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

Annotations already declare idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds useful behavioral context that isn't in the annotations: no connection is created and no quota is consumed, plus the unfollow switch. It stops short of describing exactly what state changes on unfollow, so not a full 5.

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

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

Three short sentences, front-loaded with the core action and each sentence earning its place by adding the unfollow toggle, the usage context, and the alternative. No filler.

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

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

With an output schema present, return values need not be explained, and the annotations carry the safety profile. The description covers purpose, the unfollow option, quota implications, and the connect alternative. Only minor omission is the idempotency/retry nuance, which the schema already covers.

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

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

Schema description coverage is 100%, so all four parameters (including follow, idempotency_key, account_id, linkedin_id_or_url) are already documented. The description restates the follow=false behavior that the schema already explains, adding no new parameter semantics. Baseline 3 is correct.

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

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

States a specific verb (follow/unfollow) and resource (LinkedIn member), and explicitly distinguishes itself from the connect flow by naming send_invitation. An agent can identify the tool without opening the schema.

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

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

Gives explicit when-to-use ('to follow someone's posts without a connection request') and names the alternative sibling with the selecting condition ('to connect use send_invitation'). It also notes the 'no quota' advantage, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minor domain context (a daily quota window, an activity window) but says nothing about rate limits, auth needs, or read behavior. With annotations doing the heavy lifting, a 3 is appropriate.

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

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

Two sentences with zero waste; the purpose is front-loaded and the workflow/alternative guidance follows immediately.

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?

Return format is covered by the existing output schema and safety by annotations, so the description only needs purpose and routing, both of which are complete for this single-parameter read tool.

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

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

Schema description coverage is 100% and the single account_id parameter is fully documented (including its source, list_accounts). The description adds no syntax or format detail beyond the schema, so the baseline 3 holds.

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 the quotas configuration and usage counters') scoped to a LinkedIn account, and names the sibling it complements (update_account_quotas). An agent can distinguish it from the update counterpart 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 explicit when-to-use ('before a batch to know what is left today') and routes the write case to the named alternative ('use update_account_quotas to change limits or the activity window'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: each row is a single LinkedIn call with its status, and results are paginated via limit/offset. It does not state defaults or caps for limit, which would be the remaining useful detail.

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

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

Two sentences, no filler, and the core action is front-loaded ahead of the alternative-tool pointer. Every clause earns its place.

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

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

For a read-only, idempotent log-retrieval tool with full parameter coverage, an output schema, and declared annotations, the description supplies everything an agent needs: purpose, filter, pagination, and the totals alternative.

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

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

Schema description coverage is 100%, so the schema already documents account_id, request_type, limit, and offset with examples. The description only restates the same filter/pagination concepts already present in the schema, adding no syntax or default values. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource (get request logs for a LinkedIn account) plus the scope modifiers it supports. It explicitly distinguishes itself from the sibling get_account_request_logs_stats, which handles totals, so an agent can choose 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 a concrete use case (debugging a failing account, seeing each LinkedIn call with its status) and names the alternative tool for totals. The routing condition between this tool and get_account_request_logs_stats is explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safe-read profile is fully covered by structured data. The description adds only that results are bucketed aggregates rather than raw rows, which is modest added context; it does not discuss limits, result caps, or ordering. With annotations carrying the safety burden, a 3 is appropriate.

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

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

Two sentences, zero filler; the aggregation scope is front-loaded and the routing to the sibling tool comes second. Every sentence earns its place.

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

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

An output schema exists, so return values need not be described, and the schema plus annotations fully cover inputs and safety. The description supplies the one thing structured fields cannot: the aggregation-vs-raw distinction and when to pick this tool.

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

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

Schema description coverage is 100%, so all five parameters (account_id, start/end date, group_by, request_type) are already documented in the schema with defaults and an enum. The description's mention of 'action and date-range filters' and bucket sizes only restates that, adding no syntax or format detail beyond the schema.

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

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

States a specific verb+resource ('Get aggregated request-log statistics'), names the aggregation dimension (day/week/month) and filters, and explicitly distinguishes itself from the sibling get_account_request_logs. An agent can separate this from the raw-log tool 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 concrete use cases ('weekly review', 'size an account's activity') and names the alternative ('for individual calls use get_account_request_logs') with the condition that selects it. This is the explicit when-to-use/when-not guidance the dimension asks for.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value on top by enumerating the returned status values (is_connection, SENT/PENDING/WITHDRAWN/REFUSED) and flagging the call as cheap, which helps an agent decide to probe it freely.

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

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

Three short sentences, front-loaded with purpose, then return shape, then usage. No filler, and the most decision-relevant guidance (when to call) is present without padding.

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

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

An output schema exists, so return-value documentation is not required in the description; the brief enumeration of status values is a bonus. For a two-parameter read tool with full annotation coverage, nothing an agent needs to select or invoke it correctly is missing.

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

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

Schema description coverage is 100%: account_id and linkedin_id_or_url are both documented in the schema, including accepted URL/vanity/id formats. The description adds no parameter detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource (get invitation status / connection status) and scopes it precisely: the relationship between the connected account and a given LinkedIn member. It is immediately distinguishable from siblings like list_sent_invitations or list_received_invitations, which enumerate rather than resolve one member's state.

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

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

Explicitly names the decision point: 'Use before send_invitation or send_message to know the relationship (connected, invitation pending, refused).' It names two concrete alternative tools and the condition that selects this one, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by describing the returned content shape (per-item scheduled time, result or error) and the diagnostic intent of the call. It does not mention pagination or behavior for a non-existent job_id, 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?

Two sentences with zero waste: the first front-loads what you get, the second routes the agent to the right tool for the contrasting case. Every clause earns its place.

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

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

For a single-parameter read tool with full annotation coverage and an output schema that carries the return shape, the description is complete enough to call correctly. It briefly reinforces the return content without needing to restate the output schema.

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

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

Schema coverage is 100% and the single job_id parameter is already documented in the schema as coming from create_job or list_jobs. The description adds no format, range, or resolution detail beyond that, so the baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb+resource ('One job') and enumerates exactly what it returns: status, totals, next execution time, and every item with scheduled time, result or error. It explicitly distinguishes itself from the sibling list_jobs, so an agent can select it 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 explicit when-to-use conditions ('to report progress or to see why an item failed') and names the alternative for the contrasting case ('for an overview of all jobs use list_jobs'). Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds real value beyond them: it discloses the auth mechanism (stored proxy/cookies) and the cost/rate signal ('one LinkedIn call'). It stops short of describing failure modes or error behavior, so not a 5.

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

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

Three short sentences, front-loaded with the core action and followed by usage and cost notes. Slightly jargony parenthetical ('same fields as Kanbox uses from /me') but no filler.

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

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

An output schema exists so return values needn't be spelled out, and annotations carry the safety profile. The description fully covers what an agent needs: purpose, when to call, auth path, and cost.

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

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

Schema coverage is 100% and the single account_id param is fully documented in the schema. The description refers to 'an account' generically without adding format or sourcing detail beyond what the schema's 'from list_accounts' already provides, so baseline 3 applies.

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

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

States a specific verb and resource (call Voyager /me for an account) and names the concrete return (normalized profile with name, headline, premium). This distinguishes it from siblings like scrape_profile, list_accounts, and get_account_quotas without needing to open any schema.

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

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

Explicitly says when to use it ('Use to confirm which LinkedIn profile an account is') and when not ('Not needed before every action'), and notes it costs one LinkedIn call. The alternative behavior is clearly scoped.

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

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

Annotations already declare non-read-only, open-world, idempotent, non-destructive behavior, and the description reinforces idempotency ("idempotent on LinkedIn's side") while adding genuinely new context: it consumes the daily reactions quota and acts on behalf of the connected account. Quota consumption is real behavioral information not present in the annotations.

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

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

Four short sentences, front-loaded with the action and identity, then input forms, then operational caveats. No filler, though the quota and idempotency notes could be tightened into one sentence.

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

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

An output schema exists, so return values need no explanation. The description covers identity, inputs, idempotency, and quota cost; only the already-liked edge case and error behavior are unaddressed, which is minor for this operation.

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

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

Schema description coverage is 100%, so each parameter is already documented in the schema; the description's restatement of accepted post identifiers (URL, slug, URN) adds no syntax or format detail beyond it. Baseline 3 applies.

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

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

States a specific verb (Like) on a specific resource (a LinkedIn post) with the acting identity (connected account). This cleanly separates it from comment_post and react_message, which operate on different resources/surfaces.

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

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

"Use for a light touch on a post" gives a hint of intent, and the description names accepted input forms, but it never states when to prefer it over comment_post or react_message, nor any exclusion conditions. Usage is implied rather than 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: restricted API keys yield only permitted account IDs, and the returned account_id is a prerequisite for other tools. It does not describe the return shape, but the output schema exists to cover that.

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

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

Three sentences, each doing distinct work: what it returns, the credential caveat, and the session-ordering instruction. Front-loaded with the outcome and free of filler.

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

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

For a zero-parameter discovery tool with an output schema and full annotation coverage, the description supplies everything an agent needs: purpose, ordering in a session, and how to behave when multiple accounts appear. No meaningful gap remains.

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 4 applies. The description correctly notes that the API key is implicit credential context rather than an input field.

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 ('Return LinkedIn accounts accessible with the provided API key') and scopes it by credential, which cleanly separates it from siblings like get_me or list_connections. An agent can tell what this returns without opening the schema.

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

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

Gives explicit sequencing ('Use first in every session to get the account_id the other tools need') and a branching instruction for the multi-account case ('ask which account when several are listed'). This is when-to-use guidance plus an ambiguity-resolution rule, which is more than most definitions provide.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: pagination via start/count and payload parity with the raw Voyager endpoint. It does not discuss rate limits or quota impact, 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?

Three tight clauses: what it lists, how it pages, and where to go instead. The routing information is front-loaded and no sentence is redundant.

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

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

An output schema exists so return values need not be explained, annotations carry the safety profile, and the schema fully documents parameters. The description completes the picture by clarifying scope and pointing to sibling tools for adjacent cases.

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

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

Schema description coverage is 100% – start, count and account_id are each documented in the schema. The description only restates that results are paged with start/count, adding no format, bounds, or default detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource with scope: 'List LinkedIn 1st-degree connections for an account', and even names the underlying payload parity with GET /api/linkedin/{account_id}/connections. It clearly distinguishes itself from the invitations and search siblings by naming them.

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

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

Explicitly says when to use it ('walk the account's own 1st-degree network') and routes to alternatives by condition: pending invitations → list_sent_invitations/list_received_invitations, search → scrape_search. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds value by disclosing the paging mechanism (created_before walks back in time) and the underlying API path. It does not discuss rate limits or result volume, but the existing output schema covers the return shape.

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 purpose is front-loaded in the first clause, followed by routing and prerequisite information. The sentence is dense with backticked identifiers and aliases, costing some readability, but no sentence is filler.

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

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

With an output schema present and rich annotations, the description need not explain return values or safety, and it correctly focuses on the workflow prerequisite (list_conversations first). The remaining gap is the unaddressed relationship to salesnav_list_thread_messages, which an agent choosing between the two would want resolved.

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

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

Schema description coverage is 100%, so all three parameters (account_id, created_before, conversation_linkedin_id) are already documented with sources and semantics. The description reinforces paging direction and id provenance, matching the schema rather than extending it, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('List messages in a LinkedIn conversation') and even names the underlying Voyager endpoint and the Kanbox equivalent, so the operation is unambiguous. It stops short of distinguishing itself from the similarly named sibling salesnav_list_thread_messages, leaving a small ambiguity an agent must resolve elsewhere.

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 context — 'Use after list_conversations to read a thread before replying' — and explains where the required conversation_linkedin_id originates. There is no explicit exclusion or comparison against the salesnav thread-message alternative, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds real context beyond that: it identifies the underlying endpoint and explains what each returned item's IDs are for (conversation_id as conversation_linkedin_id for messages/replies, recipient_linkedin_id for sends). It doesn't discuss rate limits or pagination edge cases, so not a 5.

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

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

Front-loaded with the purpose, then routing guidance, then return-value semantics; every sentence carries information. The parenthetical endpoint reference is slightly dense but not wasteful.

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 filtered list tool with full schema coverage, an output schema, and read-only annotations, the description covers purpose, routing to the sibling, and the meaning of returned IDs. Nothing an agent needs to select or call it correctly is missing.

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

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

Schema description coverage is 100%, so count, unread, starred, archived, account_id, and next_cursor are all documented in the schema; the description only restates the filters and paging at a high level. Baseline 3 is appropriate, though the downstream ID semantics add minor value.

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 LinkedIn messenger conversations'), scopes it to the Voyager Messaging GraphQL endpoint, and explicitly distinguishes classic inbox from Sales Navigator threads by naming the sibling salesnav_list_messaging_threads. An agent can tell it apart 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 routing rule: 'Use for the classic LinkedIn inbox (this is the one that matters in 95% of cases); Sales Navigator threads are separate.' The when/when-not and the alternative are both 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds value beyond that with ordering behavior, the fact that items are excluded from results, and the set of filterable statuses, though it says nothing about pagination or default page size behavior.

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

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

Two tight sentences, front-loaded with scope and ordering, then the usage condition. Every clause earns its place with no redundancy.

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

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

An output schema exists, so return values need not be explained, and the description still flags that items are omitted. Combined with full schema coverage and annotations, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and each parameter is documented in the schema itself (limit default, status enum, account_id provenance). The description restates the filterable dimensions but adds no syntax or format detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb+resource (list jobs), scopes it to this user, and specifies ordering (newest first) and payload shape (without items). It explicitly distinguishes itself from the sibling get_job by noting details and items live there.

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 when-to-use: 'find running or paused jobs before creating a new one on the same account,' which ties directly to create_job. It also names the alternative (get_job) for a deeper view, so the routing decision is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds non-obvious behavioral context: results carry an invitation_secret that is the prerequisite for accepting, which the agent could not infer from annotations alone. It stops short of describing pagination or result shape, so not a 5.

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

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

Two compact sentences with zero filler; the distinguish-from-sibling clause is front-loaded in the second sentence immediately after the purpose. Every clause earns its place.

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

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

An output schema exists, so return values needn't be explained, yet the description still surfaces the one output field that drives a downstream action (invitation_secret). Purpose, routing, and the accept/decline follow-up path are all present for this simple 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 100% – count, start and account_id all carry their own descriptions including defaults and the max. The description adds no parameter syntax or format meaning beyond that; the only detail it offers (invitation_secret) is a return value, not an input. Baseline 3 applies.

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

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

States a specific verb (List) and resource (pending connection invitations received by the account), plus a distinguishing scope detail ('received'). It explicitly separates itself from list_sent_invitations, so an agent can route correctly 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 a concrete when-to-use ('triage invitations waiting for the account'), names the downstream tools (accept_invitation, decline_invitation) in the right order, and names the sibling to use for the opposite case (list_sent_invitations). This is explicit when/when-not/alternatives guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint). The description adds useful behavioral context beyond that: it discloses the paged nature and the returned fields (URNs, text, scheduled publish times), and the scoping fact that only queued posts appear. It does not mention auth needs or rate limits, so not a full 5.

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

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

Three tight sentences, front-loaded with the purpose, followed by return contents and then the routing to the alternative tool. No filler.

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

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

Output schema exists, so return values need not be restated, yet the description still summarizes them. With annotations carrying safety and the schema carrying parameters, everything an agent needs to call this correctly is present.

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

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

Schema description coverage is 100%, so count, start, and account_id are already documented in the schema. The description only adds 'paged' generically without elaborating on count/start semantics, so it does not meaningfully exceed the schema baseline.

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

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

States a specific verb (List) and resource (scheduled LinkedIn posts for an account) with scope, and explicitly distinguishes itself from the sibling list_user_posts. An agent can separate it from list_user_posts 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?

Explicitly states when to use it ('to see what is queued to publish'), when not (published posts are not listed here), and names the alternative (list_user_posts) for the excluded case. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds useful semantic scope (only pending, non-accepted invitations), but says nothing about pagination behavior, result volume, or the account-connection prerequisite that annotations don't cover. With annotations carrying the safety burden, this is adequate but not rich.

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

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

Two tight sentences with zero waste. The purpose statement is front-loaded and the routing/alternative information follows immediately, so the most decision-relevant content appears first.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. The description is complete for tool selection, though it omits the pagination mechanics and the requirement that account_id come from list_accounts, which the schema covers instead.

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

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

Schema description coverage is 100% (count page size, 0-based start offset, account_id sourcing from list_accounts), so the schema fully documents all three parameters. The description adds no parameter-level guidance beyond the implied 'sent, pending' filter, which is the correct baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List pending connection invitations sent by the account') and narrows scope precisely to invitations 'that have not yet been accepted.' It also distinguishes itself from the sibling list_received_invitations by name, so an agent can route 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?

Explicitly states when to use it ('find invitations the account sent that are still pending'), names the follow-up action when data is stale ('then withdraw_invitation if stale'), and names the alternative for the opposite case ('for received ones use list_received_invitations'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered and the trailing 'Read-only' adds nothing. The description does add useful behavior: pagination via start/count and the underlying endpoint. No mention of result caps beyond the schema or 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?

Front-loaded with purpose, then pagination mechanics, then the sibling disambiguation. Three tight sentences with almost no waste, though the trailing 'Read-only.' duplicates the readOnlyHint annotation 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 paginated read tool with an output schema (so return values need no explanation) and full annotation coverage, the description supplies purpose, pagination, and alternative routing. Only minor gaps remain around result limits and the self-profile case.

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

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

Schema description coverage is 100% (count max 50, start offset, account_id origin, linkedin_id_or_url formats), so the schema carries the parameter burden. The description only hints at pagination with 'Paginate with start/count,' adding no syntax or constraint detail beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource (recent posts published by a LinkedIn member), including the underlying source profileUpdatesV2, and explicitly distinguishes the scope from engagement data. An agent can separate it from scrape_post and scrape_my_posts without opening any schema.

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

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

Explicitly names the alternative for a different need: 'to get likers and commenters of a post use scrape_post,' which is a clear when-not statement. It does not address the closely related sibling scrape_my_posts (same data for the authenticated user), so routing is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the 'Read-only' sentence largely repeats structured data. However, the description adds genuine behavioral value by enumerating the event types the endpoints are registered for and noting that the call 'also returns the event catalogue', which is not derivable from 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 with the core action and scope, then supports it with the event list and the catalogue note. The middle sentence is event-dense and slightly long, but every clause adds routing or return-value information rather than filler.

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

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

With an output schema present and rich annotations, the description need not explain return formatting, and the 'event catalogue' note usefully previews content. It is complete for a no-argument list tool, with only minor room to mention relationship to sibling read tools.

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; the baseline for a parameterless tool is 4. The description correctly implies no filtering or argument selection is required.

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

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

States a specific verb and resource ('List the webhooks registered for this user') and immediately scopes it by enumerating the exact event types that flow through those endpoints. This is clearly distinguishable from create/delete/update/test_webhook_endpoint siblings without opening any schema.

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

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

Gives an explicit use case ('Use to see where Reach already posts events and which events'), which tells the agent when this read tool is appropriate. It does not name an alternative tool or state when-not to use it, so it falls short of full routing guidance.

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

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

Annotations already declare the mutation and idempotency profile, and the description adds real behavioral context beyond them: paused jobs stay stopped until resumed, resume re-plans the job, and Reach auto-pauses/resumes on quota or disconnection. This is meaningful disclosure of side effects, though it does not address auth or what data is retained.

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 opening sentence is well front-loaded, but the auto-pause behavior is stated twice ('Reach also pauses a job by itself when a quota is reached or the account disconnects' and 'Reach pauses on quota or disconnection by itself'), which is redundant padding in an otherwise short 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?

An output schema exists, so return values need not be explained, and annotations cover the safety/idempotency profile. The description supplies usage intent and lifecycle behavior, leaving only minor gaps such as permissions needed to pause.

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

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

Schema coverage is 100%, with job_id and idempotency_key fully documented in the schema (including retry/expiry semantics). The description adds nothing new about parameters, so the baseline 3 applies.

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

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

Names a specific verb+resource (pause a job) and immediately states the effect: 'nothing more runs until resume_job is called.' It also distinguishes itself from the sibling resume_job, 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?

Gives a concrete use case ('hold a job the user is unsure about') and points to the counterpart tool resume_job. It stops short of explicit when-not-to-use guidance or prerequisites, but the context is clear enough to select the tool.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond the structured fields: the LinkedIn Premium auth prerequisite and the empty/error outcome when the prerequisite is unmet.

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 description is short, but the LinkedIn Premium precondition is stated twice ('requires LinkedIn Premium' and 'needs LinkedIn Premium'), which is redundant filler in a two-sentence 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?

An output schema exists so return values need not be described, and the description still covers purpose, precondition, and failure mode. It is close to complete for a single-parameter read tool, with only sibling routing 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?

Only one parameter and schema coverage is 100%, with the schema documenting account_id as a reach id from list_accounts. The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (Get), a specific resource (list of members who recently viewed the account's profile), and frames it against the recognizable 'who viewed my profile' concept. An agent can immediately distinguish it from scrape_profile or visit_profile 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 context ('Use for the "who viewed my profile" list') and states the gating condition (requires LinkedIn Premium) plus the failure behavior otherwise. However, it never names an alternative tool or an explicit when-not scenario against siblings, leaving routing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and non-open-world, so the safety profile is covered. The description adds real behavioral context beyond that: entries contain tool sequences, prerequisites and full instructions, and playbook_id narrows the response to one playbook. It does not discuss pagination or catalogue size, but for a static read-only catalogue that is minor.

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 'START HERE' and tightly organized, but the when-to-use guidance is stated twice ('Call this first when the user asks what you can do... or when a request is vague' then 'Use first for a vague request or what can you do'). One of those sentences could be dropped without loss.

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

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

An output schema exists, so return structure need not be explained, and the description covers everything else an agent needs: that this is a discovery entry point, what each entry contains, how to drill into one, and when to skip it entirely.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by explaining the intent of playbook_id (retrieve one playbook's instructions 'and then follow them') and flagging that include_instructions produces longer output, which helps an agent decide whether to set it.

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 ('Return the catalogue of ready-made LinkedIn playbooks') and immediately reframes it as 'what this server can actually accomplish, as named workflows rather than raw endpoints'. That framing distinguishes it from every sibling, which are all single-action endpoint 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?

Gives explicit when-to-use ('Call this first when the user asks what you can do... or when a request is vague') and explicit when-not ('not needed when the user names a precise action'). It also names the follow-up behavior (pass playbook_id, then follow the instructions), leaving nothing to inference.

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

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

Annotations already declare the safety profile (destructiveHint=false, idempotentHint=true, openWorldHint=true). The description restates the react=false removal and the mark-as-read side effect, but the same mark-as-read behavior is already in the conversation_linkedin_id schema description, so the description adds little beyond structured fields. No quota/rate-limit context despite the account quota siblings.

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

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

Front-loaded with the verb+resource and mostly tight, but it repeats the message_urn provenance twice ('returned by list_conversation_messages' and again 'message_urn from list_conversation_messages'), which slightly bloats the sentence.

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

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

Covers the mutation direction, the URN source, the side effect, and the sibling alternative; an output schema exists so return values need not be explained. Remaining gaps (permissions/scope requirements, quota behavior) are minor for a reaction toggle.

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%, setting a baseline of 3, but the description adds a concrete message_urn format example (urn:li:msg_message:(urn:li:fsd_profile:…,123456789)) that the schema lacks, plus reinforces the emoji and react semantics. It provides modest value beyond the schema but not exhaustive per-parameter guidance.

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

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

States a specific verb (add/remove) and resource (emoji reaction on a LinkedIn message), and distinguishes the action from sibling tools: like_post/comment_post operate on posts, send_message on words. An agent can identify this as thread-message reaction handling without opening the schema.

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

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

Gives explicit when-to-use ('an emoji reaction on one message inside a thread') and names the alternative and the condition that selects it ('to reply in words use send_message'). It also spells out how to undo the action (react=false).

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is partly covered. The description still adds non-derivable context: the action is irreversible on LinkedIn, the other party is not notified, and user confirmation is required. It does not restate the idempotency/retry semantics, which the schema already carries.

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

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

Three tight clauses with the core action first, the reversibility warning second, and the routing rule last. No filler and nothing an agent needs is buried.

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

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

An output schema exists so return values need no explanation, params are 100% schema-documented, and the description closes the two gaps an agent actually faces: safety/irreversibility and which sibling to use instead. Complete for this tool's complexity.

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

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

Schema description coverage is 100%, so all three parameters (including the idempotency key) are already fully documented. The description adds no syntax or format hint beyond the schema, so the baseline 3 applies.

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

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

'Remove an existing 1st-degree connection' gives a precise verb + resource + scope, and the closing clause names the sibling it must not be confused with (withdraw_invitation for pending invitations). An agent can differentiate it from withdraw_invitation 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?

States the exclusion explicitly ('Not for pending invitations, see withdraw_invitation') and adds a procedural precondition ('confirm with the user'). This is exactly the when/when-not/alternative routing an agent needs in a 50-tool namespace.

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

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

Annotations already declare readOnly=false, destructive=false, openWorld=true, idempotent=false, so the safety profile is covered. The description adds genuinely new context: the call counts against the daily comments quota and the URN is consumed directly as threadUrn. It does not reconcile idempotentHint=false with the retry-safe idempotency_key parameter, which is the one remaining disclosure 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?

Three short sentences, front-loaded with the action, then the alternative routing, then the quota constraint. Every sentence carries distinct information and none is filler.

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

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

For a single-write operation with a full output schema, the description supplies the prerequisite source for comment_urn, the sibling disambiguation, and the quota side effect. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already explains account_id, text, comment_urn and idempotency_key. The description adds only a light clarification that comment_urn equals the comment_id from scrape_post and is used as threadUrn; it says nothing about the optional idempotency_key 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 and resource ('Post a reply to an existing LinkedIn comment') and immediately contrasts with the sibling 'comment_post' for a new comment on the post itself. An agent can route between the two without opening either schema.

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

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

Explicit when-to-use plus the alternative: 'Use to answer a specific comment ...; for a new comment on the post itself use comment_post.' It also names where the required comment_urn comes from (scrape_post / scrape_my_posts), closing the main selection gap.

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

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

Annotations already declare non-read-only, idempotent, non-destructive. The description adds real behavioral detail beyond that: pending items are re-planned from now, constrained by the window and remaining quota. It doesn't cover auth or error behavior, but adds meaningful semantics.

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

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

Three sentences, front-loaded with the action, then behavior, then usage guidance. No filler; every clause carries information.

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

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

With an output schema covering return values and annotations covering the safety profile, the description fills the remaining gaps (when to call, when not to, re-planning semantics) completely.

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

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

Schema description coverage is 100% and idempotency_key's semantics are fully documented in the schema, so the description needn't repeat them. It adds no parameter-level detail, so baseline 3 applies.

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

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

States a specific verb+resource ('Resume a paused job') that is immediately distinguishable from siblings like pause_job, cancel_job, and create_job.

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

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

Explicitly says when to use it ('after a manual pause') and, crucially, when NOT to ('jobs paused for quota or disconnection resume on their own and need no call'), which prevents unnecessary calls.

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

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

Annotations already cover readOnly/idempotent/openWorld, yet the description adds real behavioral context: the {needs_disambiguation:[...]} return contract, the account_id precondition for name resolution or execute, and the fact that execute=true triggers a live page fetch. Minor gaps remain (no rate limits, no pagination/result-size caveats for execute), so not a full 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 labeled RESOLUTION/BOOLEAN/EXCLUSION/EXECUTION blocks that map to how an agent scans. Dense but every sentence adds actionable information; no filler.

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

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

For a 30-parameter tool with an output schema present, the description covers the non-obvious behaviors an agent needs: resolution fallbacks, boolean syntax, exclusions, the execute side effect, and the chained next call. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: industry and region accept ids OR names with auto-resolution rules, keywords/current_title accept LinkedIn boolean syntax, and any list item may be {id|name, exclude:true}.

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 (Build) and resource (Sales Navigator people-search URL) plus scope (from structured lead-search filters). An agent can distinguish it immediately from siblings like scrape_search, salesnav_typeahead, and salesnav_resolve_industry.

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 workflow: resolve ids first (naming salesnav_resolve_industry and salesnav_typeahead type=geo/company), call this tool to get the URL, then scrape_search on it. It also names the condition that selects the disambiguation re-call path.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds substantive context beyond them: the Sales Navigator subscription prerequisite (has_sales_nav), what is returned (threads with messages and participant profiles), and the pagination contract. It omits rate limits or quota behavior, keeping 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?

Four dense sentences with no filler: purpose, prerequisite, return shape, pagination, then routing. The prerequisite and the sibling routing are front-loaded where an agent will read them.

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 a full parameter schema, an output schema, and rich annotations, the remaining burden is routing and prerequisites, both of which are stated. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description restates the pagination flow (next_page_starts_at as page_starts_at), which duplicates the schema's own wording rather than adding syntax or edge-case detail. Baseline 3 applies.

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

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

States a specific verb and resource (list Sales Navigator messaging threads) and grounds it in the API surface (salesApiMessagingThreads). It explicitly distinguishes itself from the classic-inbox sibling list_conversations, so an agent can route correctly 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 an explicit precondition ('Only when the account has Sales Navigator and the user asks about that inbox') and names the alternative with the condition that selects it ('the classic inbox is list_conversations'). When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real value: the Sales Navigator subscription requirement and the message_count vs total_message_count pagination signal. It doesn't describe rate limits or auth failure behavior, but the pagination hint is the key operational detail.

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 useful, but the thread-id sourcing instruction is stated twice ('Use the thread id returned by salesnav_list_messaging_threads' and again 'thread id from salesnav_list_messaging_threads'), which is redundant filler in an otherwise tight blurb.

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

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

With an output schema present, return values needn't be explained, and annotations cover the safety profile; the description completes the picture with the subscription requirement and the sibling routing. Only minor gaps (no mention of error/permission outcomes) remain.

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

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

Schema coverage is 100% (baseline 3), but the description goes further by explaining that message_count returns the most-recent messages and how to detect truncation via total_message_count. That is meaningful semantics beyond the schema's simple range/default.

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

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

States a specific verb (Fetch) and resource (a Sales Navigator thread with messages and participant profiles), and even cites the underlying endpoint. It distinguishes itself from the classic-inbox equivalent by naming list_conversation_messages as the alternative.

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

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

Explicitly says to use the thread id returned by salesnav_list_messaging_threads, states the subscription prerequisite, and routes classic inbox threads to list_conversation_messages. When-to-use and when-not-to-use are both covered.

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

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

Annotations already cover readOnly/idempotent/non-destructive/closed-world; the description adds meaningful context beyond them: it is offline with no LinkedIn call, and it returns ranked candidates rather than a single answer. Minor gap is that it doesn't say what happens on an ambiguous or unmatched term.

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 return shape, then usage. Slightly repetitive – the parenthetical 'offline, no LinkedIn call' restates the earlier 'offline, no LinkedIn call' – costing a bit of tightness.

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

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

With an output schema covering the return fields and rich annotations covering safety, the description supplies exactly the missing pieces: the offline/any-language scope, cadence, disambiguation heuristic, and sibling routing. Nothing an agent needs to call it correctly is absent.

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

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

Schema description coverage is 100%, so query and limit are already documented including examples and bounds. The description adds the important 'any language' semantic but nothing further about limit or ranking behavior, so baseline 3 applies.

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

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

States a specific verb (resolve) and resource (industry name → LinkedIn Industry Code) plus the mechanism (bundled Industry Codes V2 taxonomy, offline). Explicitly distinguishes itself from salesnav_typeahead for non-industry entity types.

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

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

Names the downstream consumer (salesnav_build_search_url's `industry` filter), gives calling cadence (once per term), a disambiguation rule (pick by hierarchy path), and explicit exclusions that route to salesnav_typeahead for locations/companies/schools/titles.

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

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

Annotations only declare readOnly=false, destructive=false, openWorld=true and idempotent=false; the description adds substantive behavioral context beyond that: a subscription prerequisite and that the call consumes the daily messages quota. It does not, however, reconcile the idempotency_key parameter with idempotentHint=false, though the schema itself covers that.

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

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

Four short sentences, front-loaded with the action and scope, then alternatives, then prerequisites and quota. Every sentence carries distinct information; there is no filler.

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

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

An output schema exists, so return values need not be described. For a mutating 5-parameter tool the description covers prerequisites, correct usage vs. siblings, the thread_id origin, and quota cost — sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is already 100%, so the baseline is 3, but the description adds real value by naming the source of thread_id (salesnav_list_messaging_threads), which the schema alone does not say. It contributes nothing further about text/account_id/copy_to_crm, which the schema handles.

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 a message in an existing Sales Navigator thread') and immediately scopes it against the sibling send_message ('everything else ... goes through send_message'). An agent can distinguish it from send_message without inspecting 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?

Explicitly gives when to use it (reply inside an existing Sales Navigator thread), when not to (new messages, classic inbox), the alternative to use instead (send_message), the prerequisite (Sales Navigator subscription), and where the required thread_id comes from (salesnav_list_messaging_threads). Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), but the description adds genuinely new operational context: 'Requires a connected account' and 'One LinkedIn call per lookup,' which discloses cost/rate behavior. It stops short of describing failure modes (no match, invalid facet) or pagination behavior for count.

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 behavior and the routing rule, then the return shape and downstream usage. The 'dynamic ids' rationale is stated twice, which is mild redundancy, and the parenthetical 'geo, company, school, title…' repeats the enum already covered earlier.

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

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

With an output schema present, the description needn't explain return values in detail, yet it still names the returned fields and where the chosen id should be used next. Auth requirement and per-call cost are both disclosed, so nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it tells the agent that 'geo' yields REGION ids and which downstream URL parameter each facet maps to. It undersells the 'group' enum value entirely and mentions 'industry' only to deflect it elsewhere, leaving a small 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 ('Live Sales Navigator autocomplete') and resource (facet ids that are dynamic), and explicitly distinguishes itself from salesnav_resolve_industry, a close sibling. An agent can pick this tool without opening another 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 routing: type='geo' for region ids, company/school/title for entity facets, and redirects industries to salesnav_resolve_industry. It also names the downstream consumer (salesnav_build_search_url) and which parameter each facet feeds.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real context: the scope is limited to the account's own recent posts, the since_hours window defaults to 24, and comment URNs feed reply_comment. It stops short of rate-limit or auth notes, but against rich annotations this is solid added value.

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

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

Three sentences, front-loaded with the core action in the first clause, followed by the scoping rule and the routing guidance. No filler; every sentence earns its place.

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

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

An output schema exists, so return format needn't be described, and the annotations cover the safety profile. Combined with explicit sibling routing and the since_hours scope, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including account_id, liked, comments, max_posts and since_hours. The description only restates the since_hours window and its default, adding no syntax or format detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Fetch) and resource (likers/commenters for the account's own recent posts), and explicitly distinguishes itself from the sibling scrape_post ('for someone else's post use scrape_post'). An agent can select this over scrape_post 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?

Names the exact use case (engagement on the account's own posts) and enumerates the outputs that qualify (likers, commenters, comment URNs for reply_comment), then names the alternative tool and the condition ('someone else's post') that selects it. Nothing is left to inference.

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