Narrareach

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

Annotations already declare idempotentHint=true and destructiveHint=true, and the description reinforces rather than contradicts them by explaining desired-state idempotent retries, reread-and-verified applied changes, and the non-mutating preview mode. It also enumerates unsupported rewrite classes, which is behavioral context the annotations do not carry. Permission/auth requirements remain unstated.

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

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

Three dense sentences, front-loaded with the core action and scope, then the preview/apply switch, then guarantees and exclusions. The unsupported-rewrites list is long but earns its place by preventing misuse.

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 adds the mutation semantics, idempotency, verification, and unsupported operations. Remaining gaps are minor: revision-mismatch behavior and any authorization prerequisites are unspecified.

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 only 33%, so the description must compensate, and it does for the two most consequential parameters: apply (default false = non-mutating preview) and the revision constraint implied by 'using its exact current revision' for expectedRevision. The id and kind parameters are not elaborated, but the tool's framing (Note or Article) partially covers kind.

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

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

States a specific verb+resource+scope: preview or amend time/timezone of a scheduled Note or Article using the current revision. It implicitly distinguishes itself from amend_scheduled_note_content by declaring content rewrites unsupported, but does not address the close sibling reschedule_scheduled_item, which an agent could easily confuse with this tool.

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 flag-level guidance (apply=false for preview, apply=true after client-side confirmation), which is genuinely useful. However it names no alternative tool and offers no condition for choosing this over reschedule_scheduled_item, so sibling routing 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true), the description discloses that the edit mutates the queued delivery snapshot rather than a shared draft, that a confirmation step is expected, and that an exact current revision is required. The unsupported-schedule list adds behavioral boundaries the annotations cannot express.

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, front-loaded with the capability and immediately followed by the preview/mutation distinction and the unsupported scope. No filler, though the final unsupported-list sentence packs four conditions that could be separated for scanability.

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 mutation semantics, default behavior, and unsupported scope are covered. The main omission is the consequence of a stale expectedRevision, which matters for an idempotent-but-guarded mutation.

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

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

Schema description coverage is only 25%, so the description must compensate, and it does for id (scheduled Note id), expectedRevision (exact current revision), and apply (preview vs replacement). It does not explain what happens on a revision mismatch or the date-time format, leaving one gap.

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

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

The description states a specific verb pair and resource: preview or replace the text of a queued LinkedIn post, scoped to text-only, untouched schedules. It implicitly separates itself from the broader amend_scheduled_item and from draft-editing siblings by narrowing to queued delivery snapshots, though it never names a sibling explicitly.

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

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

It gives explicit routing: apply defaults to false for a non-mutating preview, apply=true performs the replacement only after client-side confirmation. It also states when the tool is NOT usable (provider-accepted, in-flight, media-bearing, Article schedules), which is exactly the when-to-use/when-not guidance 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 destructiveHint=true and idempotentHint=true, so the safety and repeat-call profile is covered. The description's added value — that archiving removes the draft from lists and requires prior cancellation of scheduled items — is genuine behavioral context, but it does not explain what the flag does or whether the archive is reversible.

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: the action and its effect front-loaded, then the precondition. 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. With annotations covering destructiveness and idempotency and the precondition stated, everything needed 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 coverage is 100% and the single parameter 'id' is fully documented in the schema. The description references an 'owned draft' but adds no format or syntax 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 (archive) and resource (draft), and adds a scoping detail ('owned') plus an observable effect ('no longer appears in draft lists'). It does not name a sibling like cancel_scheduled_item or update_draft, so it stops short of full sibling differentiation.

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

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

Gives a clear precondition for use: active scheduled items must be cancelled first, which implicitly routes the agent to cancel_scheduled_item/cancel_scheduled_post. It does not state when NOT to archive or contrast with update_draft.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it never says whether cancellation is reversible, what happens to the underlying content, or whether it requires ownership/permissions on the item.

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

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

A single front-loaded sentence with no filler; the verb and object come first. It is arguably too terse given the ambiguity with cancel_scheduled_post, but as a conciseness judgment it is efficient.

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

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

An output schema exists, so return values need not be described, and annotations carry the destructive/non-idempotent profile. Missing pieces are the note-vs-article routing against cancel_scheduled_post and any error or permission behavior, so it is only minimally complete for a destructive mutation.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does clarify that kind is optional and auto-detected from id. However, it says nothing about the id format (numeric vs. prefixed, note vs. article id namespace), which matters for a tool with two distinct resource kinds.

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 (Cancel) and resource (scheduled note or article), which is clear and distinguishable from mutating siblings like amend_scheduled_item or reschedule_scheduled_item. It does not, however, explicitly distinguish itself from the near-identical sibling cancel_scheduled_post, leaving the agent to infer the note/article vs. post boundary.

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

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

The description gives no when-to-use guidance, no prerequisites, and no alternatives. With cancel_scheduled_post and reschedule_scheduled_item in the sibling set, the agent gets no help deciding which cancel or reschedule path applies. It offers only implied usage from the verb.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds real value on top: the precondition that only pending posts are cancellable and that the new status is returned, which an agent needs to interpret the result.

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 precondition, then the return. Nothing is padded or repeated.

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 destructive/idempotency profile. The main remaining gap is sibling disambiguation from cancel_scheduled_item, which the description never addresses.

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 ('id') and schema description coverage is 100%, so the schema fully documents it. The description adds no format, constraint, or lookup guidance for the id, leaving this at the baseline for fully-covered schemas.

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

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

Clear specific verb+resource ('Cancel a pending scheduled post'), immediately telling the agent what happens. However, it does nothing to distinguish itself from the sibling cancel_scheduled_item, which likely has near-identical semantics, so the agent gets no help choosing between 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?

States one exclusion — already-published posts cannot be cancelled — which is useful negative guidance. But it names no alternative for those cases and gives no other context about when to prefer this over cancel_scheduled_item or reschedule_scheduled_item.

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

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

Annotations already declare readOnly=false, idempotent=true, and destructive=false. The description adds genuine behavioral detail beyond them: the note is preserved, repeated requests open the same article without overwriting edits, and the tool does not publish. This is meaningful context for a mutation tool.

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

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

Three short, front-loaded sentences with zero filler. The core action comes first, followed by the preservation and idempotency guarantees and the no-publish boundary, each earning its place.

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

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

An output schema exists, so return values need no explanation, and the description covers the key mutation semantics (preservation, idempotency, no publish). The one gap is that the parameters, especially the required draftId, are left undefined.

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?

All three parameters (writer, draftId, workspace) have 0% schema description coverage, and the description explains none of them. It never clarifies that draftId is the required note/draft reference or what writer and workspace control, so the required input's meaning must be guessed.

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

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

The description states a specific verb and resource ('Create a linked article draft from a saved note'), which is clear and distinguishes the source (a note) from a generic draft. It does not explicitly name a sibling like create_draft or schedule_article, so differentiation is implied rather than stated.

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

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

Usage is implied by 'from a saved note' and 'Does not publish', which hints that schedule_article handles publishing. However, there is no explicit when-to-use guidance or naming of alternatives such as create_draft vs create_article_from_note, leaving the agent to infer the routing.

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

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

Annotations already declare this as a non-read-only, non-destructive, non-idempotent write, and the description adds that the draft is owned by the authenticated user and returns id/title. It does not warn that repeated calls create duplicate drafts (relevant given idempotentHint=false), so it adds only modest value beyond the annotations.

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

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

Two short sentences, front-loaded with the action and scoped by ownership; no filler or repetition of the schema.

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-required-parameter create tool with full annotations and an output schema (so return values need not be described), the description covers purpose and ownership adequately. It is only missing guidance on when this is the right creation tool among the create_* 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 description coverage is 100%, so title and contentHtml semantics are already fully documented in the schema. The description adds no field-level meaning, which is the expected baseline of 3 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 ('Create a new draft') plus ownership scope ('owned by the authenticated user'), which distinguishes it from list_drafts/get_draft/update_draft. It does not explicitly differentiate from the sibling create_article_from_note, 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?

There is no statement of when to use this tool versus alternatives such as create_article_from_note, nor any prerequisites or exclusions. The context is only implied by the tool 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds that the full HTML body is returned, which is useful context, but says nothing about pagination, error cases, or whether the HTML is raw or sanitized.

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

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

A single compact sentence with the resource and payload scope front-loaded and no filler. It is as short as it can be while still conveying the scope, though it is brief enough that it forgoes useful context.

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

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

For a one-parameter read tool with an output schema and full annotation coverage, the description is essentially complete — return values and safety are handled elsewhere. The only minor gap is the absence of any error behavior for invalid ids.

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

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

Schema description coverage is 100% for the single 'id' parameter, so the schema already documents it. The description's 'by id' phrase adds no format or semantic detail beyond the schema, making the baseline of 3 appropriate.

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

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

States a specific verb and resource ('Get a single draft by id') and scopes the return payload ('including full HTML content'). This clearly distinguishes it from list_drafts, create_draft, and update_draft among the 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?

The 'single draft by id' framing implies the retrieval use case, but there is no explicit guidance on when to choose this over list_drafts or get_note, nor any note about behavior for a missing/invalid id. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds that the response includes stored metrics, which is useful scope information, but it does not explain what happens when an id matches nothing or that the operation is not idempotent despite the hint.

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

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

One sentence, front-loaded with the action and resource, with no filler. Every clause (single, by id, full content, stored metrics) 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?

An output schema exists, so return values need not be spelled out, and the description covers the input contract adequately. It is essentially complete for a simple read-by-id tool, with only behavioral edge cases (missing id, auth scope) left implicit.

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

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

Schema description coverage is 100%, including a meaningful note that an absent workspace selects the personal account, so the schema carries the parameter meaning. The description adds nothing beyond 'by id', 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), resource (note), scope (single, by id) and what is returned (full content and stored metrics). The singular 'single ... note by id' cleanly distinguishes it from the sibling list_notes.

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

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

The word 'single ... by id' implies this is the detail-lookup counterpart to list_notes, but the description never states when to prefer it or names any alternative explicitly. No prerequisites or exclusions are given.

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

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

The description frames this purely as a read ('Fetch analytics', 'Returns account-level summary data'), yet annotations declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false. A fetch-and-return tool being flagged destructive is a direct contradiction the agent has no way to reconcile. Flagged as an annotation contradiction.

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, front-loaded with the core action and followed by the return behavior. No filler, though the second sentence is somewhat dense about fallback behavior.

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

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

An output schema exists, so return values need not be explained, and the description does convey what data comes back. But the behavioral picture is incomplete and actively conflicted against the annotations, leaving the agent unsure whether this call mutates state.

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

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

Schema description coverage is only 50%, so the description should compensate for the undocumented parameter. It adds no parameter detail at all - neither the meaning of recentLimit nor the platform enum values are explained beyond what the schema already carries.

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

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

States a specific verb and resource ('Fetch analytics for a connected platform') and clarifies the two data sources it returns. However, it does not distinguish itself from the overlapping sibling get_stats_insights, so an agent cannot tell which to pick from the description alone.

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

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

No when-to-use guidance, prerequisites, or alternatives are given. The sibling get_stats_insights plausibly overlaps in scope, and nothing routes the agent between them.

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, closed-world, so the bar is lower. The description adds genuine behavioral value beyond them: data provenance caveats ('Article draft content is local and is not a provider-verified copy; queued Note content is stored on the scheduled Note') and the no-provider-contact constraint.

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 purpose is good, but the middle sentence is a laundry list of return fields ('revision, draftId, destination, timing, cover...issues, and next action') that largely duplicates the output schema, which already exists. That sentence does not fully earn 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 inspection tool with an output schema, the description covers purpose and the important provenance/staleness caveat. The main remaining gap is the unexplained 'id'/'kind' parameters, which neither description nor schema documents.

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

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

Schema description coverage is 0%, so the description must carry the burden, yet it never explains 'id' (what identifier, which namespace) and only obliquely implies 'kind' via 'Note or Article'. Two undocumented parameters are left for the agent to guess at.

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 (Inspect), resource (one scheduled Note or Article), and a distinguishing scope ('using stored Narrareach evidence without contacting a provider'). This clearly separates it from get_draft/get_note and from the amend/reschedule 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?

The phrase 'without contacting a provider' implies the usage context (a cached, non-live readiness check), but there is no explicit when/when-not guidance or named alternative (e.g. use get_draft to fetch live draft content). Usage is only implied.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so safety is covered. The description adds genuinely useful context beyond them: this reads a stored snapshot rather than live-fetching, which explains staleness and latency expectations. It does not mention pagination or auth/workspace scoping nuance.

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

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

Two sentences, zero filler, with scope and the stored-vs-live distinction front-loaded. The metric enumeration earns its space by telling the agent what a call yields.

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 7 optional params and an output schema present, the description needn't explain return values, and it correctly covers scope plus the live-data exclusion. It is nearly complete; only explicit guidance on combining workspace/publicationId scoping 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 all 7 parameters (period, from/to, platforms, workspace, contentTypes, publicationId) are already documented with defaults, enums, and constraints. The description adds no syntax, format, or interaction detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (read) and resource (stored Narrareach Stats) and enumerates the exact metric families returned. It also draws a boundary against live per-platform analytics, which cleanly separates it from sibling get_platform_analytics.

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

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

Gives a clear when-not condition ("Does not live-fetch Substack or per-platform account analytics"), routing the agent to the alternative for live data. It never names the sibling tool explicitly and offers no positive 'use this when' trigger phrase, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds the useful framing that the result is scoped to the authenticated connection and this specific account, but discloses nothing about caching, rate limits, or behavior of the nested platform/publication data beyond the field list. Note the odd idempotentHint=false on a parameterless read is not addressed.

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

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

A single front-loaded sentence with no filler, though the long comma-separated field enumeration is somewhat list-like and partially duplicates what the output schema already defines.

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

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

For a zero-parameter, read-only tool with an output schema present, the description supplies everything needed to invoke it correctly along with useful framing of what the payload represents. Return-value detail lives in the output schema, so nothing essential is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies; the description correctly implies no input is needed by describing the call as retrieving the current authenticated user rather than a targeted lookup.

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 authenticated Narrareach user') and enumerates the exact data surface returned (name, email, timezone, plan, connected platforms, publications, workspaces), which clearly separates it from siblings like list_workspaces or get_draft. An agent can identify this as the identity/bootstrap call 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?

Usage is only implied — the phrase 'the authenticated ... user' hints this is the entry point for discovering available workspaces and writers, but there is no explicit when-to-use, when-not, or named alternative. No prerequisites or call-ordering guidance is given.

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 safety is covered. The description adds the useful nuance that the note and linked article carry independent statuses and destinations, but says nothing about pagination, result shape, or auth/permission requirements.

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

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

A single front-loaded sentence with no padding. It is efficient, though the phrasing 'list a note and its linked article' reads slightly awkwardly for a listing operation.

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

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

An output schema exists, so return values need not be spelled out, and the read-only nature is covered by annotations. However, with 0% parameter documentation and no usage context, the definition is thinner than a three-parameter tool warrants.

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

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

Schema description coverage is 0% across three parameters (writer, draftId, workspace), and the description names none of them. It only implies via 'a note' that draftId selects the subject, leaving writer and workspace entirely undocumented.

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

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

States a specific verb (List) and clarifies that the resource is a note plus its linked article with independent statuses and destinations, which resolves the ambiguity of the name 'content versions'. It is clear but does not explicitly distinguish itself from siblings like get_note or get_draft.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as get_note or get_draft. The agent must infer that this is the tool for inspecting a note/article pair's publication state.

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

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

Annotations already cover the read-only, non-destructive safety profile, so the description correctly focuses on extra behavior: newest-first ordering, exclusion of archived drafts, and compact summaries without full HTML. The archived-exclusion sits in mild tension with the ARCHIVED value in the status enum, which is worth clarifying but is not an annotation contradiction.

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: scope and ordering first, then exclusions and return-shape caveats. Every clause carries information an agent needs.

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

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

An output schema exists, so return values need not be described; the description still adds the useful note that summaries omit HTML. With full annotation and schema coverage plus only three simple parameters, the definition is nearly complete, missing only a hint about the archived-filter interaction.

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 limit, query, and status are fully documented in the schema. The description adds no format or syntax detail beyond that, which is the expected 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 scoped to the authenticated user, plus ordering (newest first). It is clearly distinguishable from get_draft (single) and list_notes (different resource), though it never explicitly names those 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?

Usage is only implied: the tool lists the current user's drafts and nothing more. There is no explicit when-to-use, no guidance on choosing this over get_draft for a single draft, and no mention of pagination strategy given the absence of a cursor parameter.

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 capacity limits (20 sets, 30 hashtags per set) and a note that saving sets has no publishing side effect, but it does not describe listing behavior, return format, or pagination beyond what the output schema provides.

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

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

The description is three short sentences with no waste and is reasonably front-loaded. The middle sentence about saving behavior is slightly tangential for a list tool, but it remains concise.

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

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

For a zero-parameter read-only list tool with an output schema and clear annotations, the description supplies the relevant domain constraints (capacity limits) and safety context. Nothing an agent needs to invoke the 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?

This tool has zero parameters, so the baseline is 4. There is no parameter information for the description to add or omit, and it appropriately does not discuss parameters.

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 the resource clearly ('Personal saved hashtag sets') and implies retrieval, so the agent knows it lists saved hashtag collections. However, it does not explicitly name the verb 'list' nor distinguish itself from the sibling save_hashtag_sets, which is the most likely 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?

There is no guidance on when to use this tool versus save_hashtag_sets or other list tools. The mention of saving behavior does not help an agent decide when listing is appropriate, and no prerequisites or exclusions are given.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description usefully adds that results come from the user's saved library and are returned newest-first, but says nothing about pagination, result caps beyond 'limit', or how tag/platform filters interact.

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

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

A single, tightly written sentence with the resource and the ordering constraint front-loaded. Nothing is padded or 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 described, and all three parameters are optional. Still, for a filtered list tool the description omits pagination behavior, whether tag and platform combine, and any sense of result volume — modest gaps for an otherwise simple 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 coverage is 67%: tag and limit carry descriptions, but the platform enum parameter has none (its enum values are largely self-explanatory). The description adds no parameter-level detail at all, so the schema does the work and the baseline of 3 applies.

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

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

States a specific verb (List) and a specific resource (posts saved to the user's inspiration library), plus result ordering (newest first). This differentiates it from sibling list_* tools like list_drafts, list_notes, and list_scheduled_posts, though it never names an alternative explicitly.

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

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

The description gives no when-to-use guidance, no prerequisites, and no routing against the many sibling list tools (list_drafts, list_notes, list_reader_activities, etc.). An agent must infer from the resource name alone that this is the tool for saved inspiration content.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, yet the description frames the tool as a plain enumeration and never explains what is destructive or mutated (the refresh parameter's cache/session side effect is the only hint). The description does add the conditional authorUrn behavior, but the safety-relevant behavior implied by the annotations is left unexplained.

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, zero filler, with the base behavior front-loaded and the conditional authorUrn branch second. Every clause earns its place.

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

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

With a full input schema and an output schema present, the description does not need to describe return values; it correctly limits itself to scope plus the authorUrn branch. The remaining gap is routing context — no comparison against the sibling destination-listing tool and no reconciliation of the destructive annotation.

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 are fully documented there, including the authorUrn newsletter behavior that the description merely restates. The description adds no syntax, defaults, or edge-case semantics 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?

The description pairs a specific verb ('List') with a specific resource ('personal profiles and Company Pages available for LinkedIn Articles') and adds the conditional newsletter behavior. An agent knows exactly what comes back. It stops short of a 5 because it never names the closely related sibling list_linkedin_destinations, so the distinction between 'all destinations' and 'destinations valid for Articles' must be inferred from the scope phrase alone.

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

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

The scope phrase 'available for LinkedIn Articles' weakly implies the calling context (picking a destination when publishing an article), but there is no explicit when-to-use, no prerequisites, and no mention of the alternative list_linkedin_destinations. An agent must guess which of the two list tools to call.

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

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

Annotations already flag destructiveHint=true, readOnlyHint=false, openWorldHint=true, and idempotentHint=false. The description adds 'Refresh,' which signals a side effect beyond pure reading, but it does not explain what refresh destroys, what permissions are required, or why the operation is destructive.

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

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

Two concise sentences with the purpose front-loaded. The second sentence restates return fields that are already available in the output schema, adding minor redundancy, but overall it is efficient.

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

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

The definition is largely complete for a simple list/refresh tool: it states the resource, scope, return fields, and annotations cover safety. The main gap is the unexplained destructive refresh behavior and lack of explicit usage guidance, but the output schema and annotations reduce the burden.

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

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

Schema description coverage is 100%, so the two optional parameters (writer, workspace) are fully documented in the schema. The description adds no parameter-specific meaning, which is acceptable given the high schema 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 and resource: lists LinkedIn personal profiles and Company Pages available for Notes. The 'for Notes' scope differentiates it from list_linkedin_article_destinations, though it does not explicitly name that sibling as out of scope.

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

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

Usage is implied by 'available for Notes,' suggesting it should be used when selecting LinkedIn destinations for note publishing. However, there are no explicit when-to-use, when-not-to-use, or alternative-tool instructions.

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 genuinely useful behavior beyond them: the result is served from a cached saved list unless refresh is set, and canPublish=false means editorial review with content held unpublished until editor acceptance. That caching/staleness disclosure is the kind of trait annotations cannot express.

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

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

Two sentences, front-loaded with the scope and followed by the caching rule and output interpretation. Nothing is padding, though the second sentence is dense and partly restates the schema's refresh semantics.

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 enumerated, yet the description still supplies the one interpretation that matters (canPublish meaning) plus the cache/refresh behavior. Combined with rich annotations and full schema coverage, an agent has everything needed to call and interpret 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?

There is a single parameter with 100% schema description coverage, so the schema already defines refresh. The description's 'Uses the saved list unless refresh is true' paraphrases the schema rather than adding format or side-effect detail, 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 names a specific verb (List) and resource (Medium publications) and scopes it precisely: publications with writer access or higher on the connected account. That resource is clearly distinct from siblings like list_linkedin_destinations or list_workspaces, so an agent can route without opening schemas.

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

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

It gives a clear operational condition — 'Uses the saved list unless refresh is true' — and explains what the output means for the publish decision (canPublish true/false). It stops short of naming alternatives or when-not-to-use guidance, so it is strong context without explicit exclusion rules.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds meaningful scope context: notes are returned across platforms and across all lifecycle states, and engagement snapshots are included "when available." It says nothing about pagination or ordering, so additional disclosure is limited.

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 no filler; the platform scope is front-loaded and the status/snapshot detail follows. 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?

An output schema exists, so return-value explanation is unnecessary, and all six parameters are optional. However, for a 6-parameter, 9-value-status filter tool, the description omits how filtering narrows results and what the default/unfiltered behavior yields, leaving the agent to infer this from the schema alone.

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 67%, with the two enum params (status, platform) having no descriptions in the schema at all. The description's mention of "scheduled, failed, and posted notes" hints at the status filter but does not explain the status/platform/query/limit interactions or defaults. It neither compensates fully for the coverage gap nor is entirely silent.

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

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

The description gives a specific verb and resource ("List the user's notes") and scopes it to "every supported note platform," plus clarifies the status coverage (scheduled, failed, posted). It is clearly the collection-level counterpart to get_note, though it never explicitly names siblings like list_scheduled_items or list_drafts to sharpen the boundary.

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

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

There is no explicit when-to-use guidance and no alternatives are named, even though several siblings overlap heavily (get_note for a single note, list_scheduled_items, list_drafts). The reader must infer from the tool name and status list that this is the cross-platform all-statuses listing.

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 safety and idempotency profile is covered. The description adds useful context that the data comes from Substack via an authenticated Narrareach account. It does not, however, disclose pagination behavior (a cursor param exists) or default result sizing, so it adds only modest value beyond 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?

A single efficient sentence with the core verb and resource front-loaded and no filler. It is not verbose, though its brevity borders on under-specification for a six-parameter tool rather than earning full conciseness credit.

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. However, for a tool with six parameters including pagination and an inbox/history state toggle, the description omits how to paginate, filter by state, or sort. Given the 0% schema coverage, the definition is not complete enough to guide correct invocation of the non-trivial parameters.

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

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

Schema description coverage is 0% across six parameters, so the description must compensate and largely does not. It names likes, comments, and restacks, which loosely maps to the 'type' enum, but the important 'state' enum (inbox vs history), 'sort', 'limit', 'cursor' pagination, and 'substackConnectionId' are all left unexplained. Only one of six parameters receives any implicit 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?

The description uses a specific verb ('Pull') with a concrete resource ('Substack likes, comments, and restacks') and scopes it to 'the authenticated Narrareach account.' An agent can tell this is a read/list tool for reader engagement data. It does not explicitly differentiate from siblings like reply_to_reader_activity or update_reader_activity, which keeps it 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?

There is no when-to-use guidance, no mention of alternatives among the ~34 sibling tools, and no exclusions or prerequisites. The agent is left to infer that this is the listing tool versus the reply/update siblings. No usage context is provided.

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/closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: 'Reads stored evidence without contacting a provider,' plus what the view surfaces (destination, readiness checks, provider receipt state, next action) and the privacy rule for team Articles.

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 dense sentences that front-load the core action and its scope; there is little waste. The phrase 'stored provider receipt state' is jargon-heavy but earns its place as returned-field context.

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, and annotations cover safety. However, for a 7-parameter tool with 29% schema coverage and no usage routing, the description leaves an agent guessing about date-range and status filtering.

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 only 29%, so the description must carry weight, yet it clarifies only the workspace/writer authorization semantics and says nothing about the from/to date bounds, kind, status, or limit parameters. Five of seven parameters remain undocumented in both places.

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 items = Notes and Articles), and the phrase 'one bounded schedule view' scopes it. It implicitly distinguishes itself from list_scheduled_posts by naming Notes and Articles, but never says so explicitly.

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

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

The description explains authorization scope ('workspace and writer scope authorized team Notes') but gives no when-to-use condition, no exclusions, and no routing to siblings like get_scheduled_item_readiness or list_scheduled_posts. The agent must infer its place from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=false and openWorldHint=false, so safety is covered. The description adds one genuinely useful behavioral fact not in annotations: results are ordered by scheduled time ascending. It says nothing about pagination despite the limit param, which is a notable gap for a list tool.

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

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

A single compact sentence that front-loads the resource and scope, then adds ordering. No filler or redundancy.

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

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

Output schema exists so return values need not be explained, and annotations cover the safety profile. However, the description omits pagination/result-volume behavior and any disambiguation from list_scheduled_items, leaving moderate gaps for a filtered 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 coverage is 75%, close to the high-coverage threshold, and to/from/limit are already documented in the schema. The description adds no parameter meaning at all, and the status enum has no schema description either, though its values are self-explanatory.

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 posts), plus scope (authenticated user) and ordering. It does not differentiate itself from the near-identical sibling list_scheduled_items, which an agent could easily confuse it with.

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

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

No guidance on when to use this versus list_scheduled_items or list_scheduled_posts alternatives, and no stated prerequisites. Usage must be inferred purely from the name and scope phrase.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond them: it returns identifiers only and requires no login switch, meaning it exposes all authorized contexts in one call. It does not mention pagination or ordering, but for a no-param read this is solid.

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, with the scope statement front-loaded and the auth note second. Every clause earns its place.

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

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

For a zero-param, read-only tool with an output schema and full annotation coverage, the description supplies enough to call it correctly. The only gap is routing guidance relative to the other list_* tools, which is not strictly required here.

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

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

Zero parameters, so the schema baseline is 4 and there is nothing for the description to disambiguate. The description instead characterizes the return payload, which the output schema covers, so no additional credit or penalty 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 clear resource set — workspaces, writers, publications — and what it returns (identifiers for team scheduling). 'Discover' is a slightly softer verb than 'list', but the object is concrete enough that an agent can distinguish it from siblings like list_medium_publications or list_linkedin_destinations.

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

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

The phrase 'for team scheduling' implies when this tool is useful (before scheduling team content), but no alternative or exclusion is named, and the many list_* siblings are not addressed. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds genuinely new context — that a successful reply moves the activity to History — which tells the agent about a state transition beyond the annotations. It does not describe auth requirements or what specifically is at risk, so it stays at a 3.

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 the core action front-loaded and the outcome stated second. No filler or repetition, though it is arguably too terse given the undocumented parameters.

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 carry the safety profile. However, with 0% schema coverage on four parameters, the description should say more about the inputs than it does, leaving the definition only minimally complete for a mutation tool.

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

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

Schema description coverage is 0%, so none of the four parameters are documented anywhere. The description mentions no parameters at all — not activityId, text, idempotencyKey, or substackConnectionId — leaving the agent to infer meaning purely from names and types. It fails to compensate for the coverage gap.

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

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

States a specific verb and resource: 'Publish a reply to an owned Substack comment activity.' The word 'owned' scopes the operation, which helps an agent avoid using it on arbitrary activities. It does not explicitly name how it differs from the sibling update_reader_activity, keeping it just 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tools are named. The only implicit condition is 'owned' activity, which is a constraint rather than a routing instruction. An agent must infer that update_reader_activity or list_reader_activities are the neighboring alternatives.

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

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

Annotations already declare destructive=true, idempotent=false, openWorld=true. The description adds two genuinely useful behavioral facts beyond them: the LinkedIn session-sync no-op case and the returned advisories. It still never warns that the prior schedule is replaced (the destructive implication) or that the call is non-idempotent.

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 compact sentences with the action front-loaded, followed by the operational caveat and return note. Little waste, though the 'Returns the outcome and informational advisories' sentence is slightly redundant given an output schema exists.

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 are covered, and the LinkedIn 20-minute lead time lives in the schema. For a destructive, non-idempotent mutation across an open-world LinkedIn integration, however, the description omits permission requirements and the consequence of replacing an existing schedule.

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 50%, and the description only expands on kind, explaining the auto-detection fallback that the schema does not state. timezone and the lead-time semantics of scheduledFor are documented in the schema itself, so the prose adds only a marginal amount beyond structured fields.

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

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

States a specific verb (reschedule) and resource (a scheduled note or article), and clarifies that kind may be supplied or auto-detected by id. It does not differentiate itself from the sibling amend_scheduled_item, so an agent still has to guess which mutation to pick.

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

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

There is no when-to-use guidance and no mention of alternatives such as amend_scheduled_item or cancel_scheduled_item. The only conditional statement ('pending LinkedIn session sync...') describes behavior, not selection criteria.

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, destructiveHint=false and idempotentHint=true; the description usefully adds that saving never inserts hashtags into content or publishes anything, directly addressing the main side-effect fear for a write tool. It does not, however, explain whether existing sets are replaced or appended to, which matters given idempotentHint=true.

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 resource and the most important behavioral guarantee, with no filler. Slightly terse at the cost of completeness, but 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 limits plus no-publish guarantee cover the essentials for a single-parameter write. The definition still leaves overwrite/append semantics and hashtag formatting unstated, which an agent needs 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 0%, so the description must compensate. It does surface the key caps ('Up to 20 sets, 30 hashtags per set') that match the schema's maxItems limits, but it says nothing about the name field, hashtag format (with or without '#'), or whether the payload replaces existing saved sets.

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 the resource precisely ('Personal saved hashtag sets') and implies the save/store action, which is enough to distinguish it from the read-only sibling list_hashtag_sets. It does not explicitly name that sibling, so differentiation is inferred rather than stated.

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

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

There is no explicit when-to-use guidance, no prerequisite or permission notes, and no reference to the alternative list_hashtag_sets for reading sets back. The only usage-adjacent signal is the reassurance about side effects, which is behavioral rather than situational.

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

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

Annotations cover the safety profile (not read-only, not idempotent, open world), and the description adds real behavioral context beyond them: draft creation vs. scheduling an existing draft, Substack-only paywall/subscribe markup behavior, and the LinkedIn session-sync fallback that silently saves as a draft. It does not discuss retry/rate semantics, hence 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?

Purpose and primary mode selection are front-loaded, and each sentence carries distinct information (draft creation, media/paywall rules, LinkedIn caveat, return advisories). It is dense but not padded; a slightly tighter grouping of the Substack paywall sentences would earn 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?

For a 23-parameter multi-destination tool, the description covers the cross-cutting behaviors an agent needs (draft-vs-schedule branch, destination constraints, degradation paths) and an output schema handles return values. It omits guidance on which sibling to use for amending or cancelling already-scheduled items, leaving a small gap.

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

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

Schema description coverage is 96%, so the schema already documents nearly every parameter in depth; the baseline is 3. The description's parameter-level statements (media/video requires Substack as sole platform, paywall markers create native paywalls, audience/email governed by supplied fields) largely restate schema text rather than adding new interpretation.

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

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

Opens with a specific verb+resource+destination scope ('Schedule an article to Substack, Medium, LinkedIn Articles, or X') and immediately states the draft-creation behavior. An agent can distinguish it from schedule_note, create_draft, and reschedule_scheduled_item 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 clear situational context: draftId absent means a new draft is created, LinkedIn Articles needs a separate browser-session connection, and a pending session sync degrades to draft-without-scheduling. It does not name sibling alternatives (e.g. amend_scheduled_item, reschedule_scheduled_item) for when-not scenarios, so it stops short of a 5.

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

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

Goes well beyond the annotations (which only declare non-readonly, open-world, non-idempotent, non-destructive) by disclosing character limits per platform, the sentence-boundary truncation behavior with adjustedPlatforms and warnings in the response, the all-or-nothing rule for explicit platformVersions, and Substack profile-routing safety that can return action_required without publishing. These are non-obvious side effects an agent must anticipate.

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

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

Purpose is front-loaded in the first sentence and the remainder is information-dense rather than padded. Some sentences are long and pack multiple constraints (character limits plus truncation plus routing rules) that would read better as a short list, but there is little actual waste.

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

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

For a 20-parameter, nested-object tool with an output schema, the description covers the high-risk behaviors (draft-vs-draftId path, platform limits, truncation reporting, Substack identity failures) that the schema alone would not convey. It leaves media attachment and Instagram destination handling entirely to the schema, which is a minor remaining gap.

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

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

Schema coverage is already 95%, so the baseline is 3, but the description adds genuine meaning: platform-specific limits tied to platformVersions, team routing via workspace/writer, and the Substack publication/profile requirement. It does not cover media, imageUrls/videoUrls, or instagramDestinations, so it is not exhaustive.

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 ('Schedule a note') plus the exact set of target platforms, so the agent knows precisely what the tool does. It distinguishes implicitly from the sibling 'schedule_article' by using 'note', but never names or contrasts siblings explicitly, keeping it below a 5.

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

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

Gives useful conditional context — 'Creates a note draft when draftId is absent' and 'Authorized team routing uses workspace and writer' — which helps the agent pick the right call shape. However, it never states when to prefer this tool over siblings like schedule_article or create_draft, nor any explicit exclusions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the mutation profile is covered. The description adds genuine context beyond that: it is a partial/patch update ('only the provided fields are changed'), it enforces an ownership boundary, and it warns that editing a scheduled item's local draft won't propagate to the provider.

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

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

Three sentences, front-loaded with the core action and constraint, each earning its place. It is slightly dense in the last sentence but not padded.

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

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

An output schema exists so return values need not be explained, and the description covers scope, ownership, and the scheduling hazard. What remains unstated is the exact replacement workflow/tool for scheduled items, but overall it is complete enough to call 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%, including nested coverImage fields, so the schema carries parameter meaning and baseline 3 applies. The description adds patch semantics ('only the provided fields are changed') but no per-field 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 ('Update an unscheduled draft') and immediately scopes it away from scheduled Articles, which is exactly the ambiguity that separates it from amend_scheduled_item and cancel_scheduled_item. The agent can select the right sibling 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 says when NOT to use it (active scheduled Articles must go through a provider-safe schedule workflow) and states an ownership precondition. It stops short of naming the exact alternative tool (amend_scheduled_item) to use instead, so it is strong but not fully routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description only adds the 'owned' ownership qualifier and the destination names; it does not explain the consequence of a destructive 'move to History' or whether the change is reversible.

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

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

A single front-loaded sentence with no wasted words. It is efficient, though it leans toward under-specification rather than economy.

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 mutation with an output schema available, the description should at least clarify the effect of the state change and the third parameter. With 0% schema coverage and no usage guidance, an agent lacks enough to call this confidently.

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

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

Schema description coverage is 0%, so the description must carry the load and does not. It implies the activityId (owned reader activity item) and the triageState destinations (Inbox/History), but gives no format for activityId and never mentions substackConnectionId at all.

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 (move), a specific resource (owned reader activity item), and the destination states (Inbox or History). It is clear enough to distinguish from list_reader_activities and reply_to_reader_activity, though it never names or explicitly contrasts those 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as list_reader_activities or reply_to_reader_activity. The agent must infer the use case entirely from the 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?

Annotations already declare readOnly=false, idempotent=false, openWorld=true, destructive=false. The description adds genuinely new context beyond those: URL ingestion depends on the source host permitting automated access (an external-dependency caveat), and the call returns a public media URL. It does not, however, warn that repeat uploads are non-idempotent (duplicates), leaving one behavioral gap.

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

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

Three tight sentences with zero filler; the supported ingestion modes and the host caveat are front-loaded, and the doc link is relegated to the end. Every sentence earns its place.

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

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

For a 6-parameter tool with 83% schema coverage and an output schema, the description covers ingestion modes, the external dependency risk, and the return value. Nothing an agent needs to invoke it correctly appears 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 83%, so the baseline is 3. The description goes further by enumerating the three accepted source forms (HTTPS URL, data URI, base64 bytes) and flagging the host-access caveat, which complements the schema's per-field notes on base64/blob: limitations and mimeType requirements.

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 ('Upload one image or video') plus its purpose ('for later scheduling') and the three supported ingestion modes. An agent can distinguish it from every sibling (create_draft, schedule_note, etc.) without opening a schema.

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

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

The phrase 'for later scheduling' implies this precedes a scheduling call, giving some usage context, but it names no explicit alternative tool, no when-not conditions, and no prerequisite steps. 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.