Narrareach

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

Far exceeds what the annotations carry. It discloses refusal conditions (already goes to that platform/account or posted in the last day, time passed or changed, Substack), the idempotency contract with clientRequestId and the replayed:true response, and the content fallback logic. These are exactly the behavioral traits an agent cannot derive from readOnlyHint/idempotentHint alone.

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

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

Front-loads purpose and the sibling distinction before the operational detail, and each sentence carries real information (refusals, idempotency, content sourcing). It is dense and reads as one long block rather than clearly segmented sections, which taxes scanning, but there is little filler.

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

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

An output schema exists, so return values needn't be spelled out, and the description still notes it returns the new version(s) and scheduled time. Combined with the refusal conditions, account-selection path, and idempotency rules, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics beyond the schema: the omission-fallback rule for content ('the same platform's version, else the longest that fits... shortened to fit with adjustedPlatforms and warnings'), and the account-selection requirement. It clarifies behavior rather than merely restating field descriptions.

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

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

States a specific verb and resource ('Add a platform (or another account on a platform) to a Note that is already scheduled') plus the downstream effect ('so it posts there at the same time as the Note's other versions'). It explicitly distinguishes itself from the nearest sibling, schedule_note, so an agent can route correctly without opening either schema.

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

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

Gives an explicit selection rule ('Use this, not schedule_note, whenever...') and explains what schedule_note would do instead (create a separate Note). It also enumerates the platforms in scope and the operating rule 'Ask the writer, never pick', leaving nothing to inference.

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

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

Annotations already declare it is a non-read-only, non-destructive, idempotent, closed-world write. Beyond that, the description discloses the downstream effect ('Future drafts draw on it instead of making things up') and a hard authorship constraint, which are genuine behavioral traits not derivable from the annotations. It says nothing about duplicate handling, whether entries can be edited or removed, or what the call returns.

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

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

Two sentences, no filler. The what/where is front-loaded and the fabrication prohibition closes it, so the most consequential rule is the last thing read before acting.

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

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

With an output schema present, return values need not be described, and the schema fully documents all four parameters. The description covers purpose, effect, and the core constraint, leaving only secondary gaps: duplicate/repeat behavior for an idempotent write, and the workspace-versus-personal-account scoping that the writer/workspace params imply.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by defining what each enum value actually means in practice (a story they lived, a number they measured, an opinion they hold, an example they use), which reduces misclassification between 'opinion' and 'example'. The writer/workspace scoping parameters are untouched.

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 ('Save ... to their material bank') and enumerates the four material kinds (story, number, opinion, example), so the agent knows exactly what lands in the bank. It does not name a sibling such as save_voice_preference or update_voice_rule, so the boundary between 'material' and 'voice rule/preference' must be inferred from the resource noun 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?

Gives a clear trigger ('something real the writer has just told you') and an explicit exclusion ('Save only what the writer supplied; never add anything you wrote or assumed'), which is the key failure mode for this tool. It never names an alternative tool or states what to do when the writer's input is not real material, so routing against siblings is left implicit.

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

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

Goes beyond the annotations by disclosing idempotent desired-state retries, that applied changes are reread and verified, and the explicit list of unsupported rewrites (cover, content, paywall, email-delivery, destination). This adds real behavioral context, though the safety profile (destructiveHint, openWorldHint) is already carried by annotations.

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

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

Dense but front-loaded, with the core action and scope stated first and constraints following. Every clause earns its place, though the single run-on sentence packs several distinct ideas together.

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

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

Given an output schema exists, return values need not be explained, and the description covers preview vs mutation, idempotency, verification, and unsupported operations. The main remaining gap is routing guidance relative to the similar reschedule_scheduled_item sibling.

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 33%, and the description compensates partially by clarifying apply's default and semantics and expectedRevision as the exact current revision. But id and kind receive no explanation anywhere, so the description does not fully close 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 (preview/amend) and resource (scheduled Note or Article) with a clear scope restriction (time or timezone only via exact current revision). However, it never distinguishes itself from the sibling reschedule_scheduled_item, which sounds like an overlapping operation, leaving the agent to guess which 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?

Explicitly explains the two modes: apply=false for non-mutating preview and apply=true to perform the amendment after client-side confirmation. It gives clear context for when each path is appropriate, though it does not name an alternative sibling tool or state when to prefer it over 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 destructiveHint=true and idempotentHint=true, but the description adds crucial nuance: destructive behavior is conditional on apply=true, apply defaults to false for a non-mutating preview, and replacement follows client-side confirmation. It also clarifies the mutation targets the queued delivery snapshot rather than a shared draft, which annotations cannot convey.

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

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

Four dense sentences with no filler; the preview/replace distinction and constraints are front-loaded. Slightly information-heavy but every clause earns its place.

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

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

An output schema exists, so return values need not be described. Given the annotations and schema, the description covers purpose, applicability constraints, mutation semantics, and the preview/apply switch, making it largely self-sufficient; only explicit alternative routing to amend_scheduled_item is missing.

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

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

Schema description coverage is only 25% (content only), so the description must compensate and largely does: it explains id as the scheduled Note id, expectedRevision as the exact current revision, and apply's default and semantics. It adds meaningful meaning beyond the bare schema types.

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 pair ('preview or replace') and a precise resource ('the text of an untouched, text-only queued LinkedIn post'), plus the required identifiers. It differentiates from shared drafts ('not a shared draft') but never names the closest sibling, amend_scheduled_item, so the sibling distinction is only partial.

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

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

Explicit when-to-use (untouched, text-only queued post with exact revision) and when-not (provider-accepted, in-flight, media-bearing, and Article schedules unsupported). It also clarifies the apply=false preview path versus the apply=true mutation path, leaving little to inference.

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

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

Annotations already declare 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, openWorldHint=true and readOnlyHint=false, so the safety profile is covered. The description adds essentially nothing beyond them: it does not say whether cancellation is reversible, what happens to the underlying content, or what permissions are required.

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

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

A single front-loaded sentence with no filler. The trailing clause 'with optional kind or automatic detection by id' is slightly dense but still earns its place by clarifying parameter 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 needn't be described, but for a destructive, non-idempotent mutation the definition should disclose side effects or preconditions. Nothing about post-cancel state, error conditions, or how it differs from cancel_scheduled_post is provided.

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. It usefully explains that kind is optional and can be auto-detected from the id, which is genuine added meaning, but the id parameter's format/expected value is left entirely unexplained.

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

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

States a specific verb (Cancel) and resource (scheduled note or article), making the intent clear. It does not differentiate from the very close sibling cancel_scheduled_post, which the agent must disambiguate on its own.

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 cancel_scheduled_post or amend/reschedule_scheduled_item, and no stated prerequisites (e.g., item must be in scheduled state). The only usage-adjacent hint is that kind may be omitted, which is really a parameter detail.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description goes beyond them by delimiting the blast radius — it cancels only the code request and does not touch schedules, drafts, or the Substack connection — which is exactly the kind of added context that matters for a destructive call.

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

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

Three short sentences with the core action front-loaded, followed by exclusions and a usage gate. No filler, no redundancy.

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

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

With an output schema present, return values need no explanation, and the description covers scope, exclusions, and the trigger condition. It stops short of mentioning the resume-after-verification flow implied by scheduledPostId, but that is already carried in the schema.

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

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

Schema description coverage is 100%, so the schema already explains id, connectionId, and scheduledPostId in detail. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a precise verb+resource ('Cancel the selected code request') scoped to the connected account owner, and explicitly fences itself off from adjacent mutations (article schedules, drafts, disconnecting Substack). An agent can distinguish it from cancel_scheduled_item/cancel_scheduled_post without opening a schema.

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

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

Gives a clear directive: 'Use only when the user wants to cancel this verification request,' which is a real when-to-use constraint. It does not, however, name the sibling alternative (e.g. complete_substack_verification or get_substack_verification_status) for the case where the user wants to proceed rather than cancel.

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

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

Annotations declare the mutation/no-idempotency/open-world profile, and the description adds real value beyond that: confirmation can resume previously approved articles waiting on the connection, and 'it is not proof of publication' guards against a false-success read. The never-repeat-a-code caution is an extra behavioral constraint 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 tight sentences, action front-loaded, no filler. The 'never guess' prohibition and the after-care sentence are both load-bearing; the only mild redundancy is the dual mention of the same connection/code request.

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 mutating, non-idempotent step in a multi-tool verification flow, the description covers the key side effect (resuming pending articles), the failure mode (not proof of publication), and the follow-up path. An output schema exists, so return values need no explanation here.

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

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

Schema description coverage is 100%, so the schema already defines id, code, connectionId, and scheduledPostId. The description gestures at the connection/code-request linkage and at retrying the saved draft, but adds no syntax or format detail beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ('submit the six-digit code') and pins the scope to 'the same connection and code request.' It is clearly separable from start_/cancel_/get_substack_verification_status by virtue of being the code-submission step, though it never names those siblings explicitly.

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

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

Gives explicit when-not guidance ('Never guess or automatically repeat a code') and post-call guidance ('check an existing schedule afterward, or retry the same saved draft'). What's missing is an explicit pointer to start_substack_verification/get_substack_verification_status as the prerequisite steps, so the ordering is only implied by 'same connection and code request.'

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

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

Annotations 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?

Adds real behavioral context beyond annotations: it persists nothing, enforces up to 10 notes per call and 20 calls per day, and a call can take a minute or two. It also explains the chaining contract (pass note as content, suggestedTime unchanged as scheduledFor, requestId as generationId). Doesn't contradict the readOnlyHint=false/destructiveHint=false profile.

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

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

Front-loaded with purpose, then the scheduling workflow, then limits. It's a dense single paragraph but every clause earns its place; a slightly tighter structure with the limits broken out would be the only improvement.

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 12-parameter, non-mutating generation tool with an output schema, it covers purpose, downstream workflow, rate limits, latency, and workspace-scoping caveats. Nothing an agent needs to invoke and chain it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds value by tying parameters to the downstream call (workspace, platforms, suggestedTime as an absolute time). It meaningfully clarifies how the schema fields carry into scheduling rather than restating them.

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

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

States a specific verb+resource ('Generate short notes in the writer's voice') plus the two source modes (own writing/profile vs. a passed-in article or post). It also distinguishes itself from siblings by explicitly noting it 'saves and schedules nothing,' separating it from schedule_note and create_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?

Explicitly routes the agent: show notes to the writer, then schedule approved ones with schedule_note (or schedule_notes for batches), and use create_draft only to keep an unscheduled note in the personal account since it cannot save into a team workspace. When/when-not and alternatives are all named.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is partly covered. The description still adds real behavior the annotations don't: voice-based generation when text is omitted, the returned artifacts, and the key negative 'Does not publish' that bounds the side effect.

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

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

Four short sentences, front-loaded with the core action and ending with the critical 'Does not publish' constraint. Every sentence earns its place with no filler.

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

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

With annotations covering safety and an output schema present, the description needn't explain return shape, yet it still names the returned artifacts. It is complete enough to call the tool correctly, with the only gap being the undocumented connection/activity 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 three parameters, so the description must carry the load. It only addresses one parameter ('Generates in the writer's voice when text is omitted'), implicitly conveying that text is optional and auto-filled, while activityId and substackConnectionId go entirely unexplained.

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

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

Specific verb (Save) plus resource (owned comment reply / reader reply draft) with the lifecycle stage (for review) called out. It implicitly distinguishes itself from the send/publish sibling with 'Does not publish', but it doesn't name any alternative explicitly, so it falls just short of the top band.

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?

'Save ... for review' and 'Does not publish' imply you reach for this when you want an unpublished draft rather than a sent reply, but there is no explicit when-to-use guidance or mention of alternatives like update_reader_reply_draft, send_reader_reply_draft, or reply_to_reader_activity. Usage is inferable 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 that this is not read-only, not idempotent, and not destructive. The description adds useful behavioral context beyond that: 'approve' creates a rule, 'later' defers for a week, and only one suggestion can be decided per call. It does not cover permissions or auth requirements, but it adds meaningful workflow behavior.

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

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

The description is compact and front-loaded: it names the action first, then gives usage rules and decision semantics. Every sentence contributes directly to correct invocation.

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

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

Given the rich schema, annotations, and output schema, the description provides everything an agent needs to call this tool correctly. It covers when to call, how to interpret decisions, one-per-call behavior, and the do-not-decide-for-the-writer constraint.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description still adds semantic value by clarifying that text is only used with 'approve' and only when the writer rewords the rule, and by explaining the behavioral effect of each decision enum. It does not add much for writer/workspace 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?

The description states a specific verb and resource: 'Record the writer's answer to one suggestion from get_voice_profile.' It distinguishes the tool from siblings by tying it directly to the suggestion workflow and clarifying that it records one decision per call.

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

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

It gives explicit usage conditions: ask the writer first, call only after they answer, and never decide for the writer. It also defines what each decision value means in workflow terms, leaving no ambiguity about when this tool is appropriate.

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, but the description adds what they cannot: it is advisory only, never modifies the draft, never blocks scheduling, and it instructs the agent how to handle output (offer topFixes, evaluate needsJudgment itself, never invent facts). That output-handling guidance is genuinely beyond the structured metadata.

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

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

The description is long but front-loaded: purpose and checklist first, then usage triggers, then behavioral constraints and edge cases. Each sentence carries distinct information, though the checklist enumeration and the trailing instructions could be tightened slightly.

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

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

An output schema exists, so return values need no explanation. The description covers the audit scope, when to invoke, the advisory/no-side-effect guarantee, and the published-article edge case — everything an agent needs to call and act on this tool correctly.

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

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

Schema coverage is 100% and the single draftId parameter is fully documented in the schema ('Article draft id from list_drafts'). The description adds no format, sourcing, or validation detail for the parameter, so the schema does all the work — baseline 3 applies.

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

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

States a specific verb and resource (audit an article draft for AI search visibility) and enumerates the exact signals it inspects — opening answers, headings, links, sourced figures, lists, alt text, CTA, title length. This makes it immediately distinguishable from siblings like get_draft (retrieval) and update_draft (mutation).

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

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

Gives explicit triggers — 'call it before scheduling an article' and 'when the writer asks how to make a post easier to find' — plus an explicit alternative for the published-article case ('give the writer revised sections to paste... instead of calling update_draft'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real value beyond them: the privacy guarantee that only counts are returned and no subscriber rows leak, plus the owner-only and plan-tier authorization requirement.

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

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

Front-loaded with the primary answer (is Audience ready), followed by the payload summary and then the hard constraints. The single long opening sentence is dense but every clause earns its place; the brevity of the follow-on clauses keeps it tight.

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

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

With an output schema present, return values need not be spelled out, and the description still flags what is not returned. Requirements (owner-only, plan tier) and scope (counts versus subscriber data) are covered; only error/readiness-failure behavior is left unstated.

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

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

Schema description coverage is 100% and both parameters are optional with their own documented defaults, so the baseline is 3. The description reinforces the ownership constraint on workspace but adds no syntax, format, or fallback detail beyond what the schema already states.

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

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

Specific verb and resource — verifies Audience readiness for a Substack publication and enumerates exactly what it returns (filter columns with operators/values, tag and segment counts). 'Counts only; never returns subscribers' sharply distinguishes it from preview_audience_segment, which an agent could otherwise 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?

Frames the use case clearly (a readiness/preflight check) and states the eligibility gate: workspace owner only, on a plan that includes agents. It stops short of naming when to use this instead of preview_audience_segment or what to do if the readiness check fails, so it is clear context without 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The description's one added fact, that the response includes full HTML content, is useful context about payload weight, but it says nothing about size limits, permissions, or error behavior on a missing id.

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

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

One sentence, front-loaded with the verb and resource, and the payload note is appended rather than buried. Nothing is wasted and nothing extra is needed.

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 annotations covering safety and an output schema covering the return shape, the description says enough to call it correctly. The only mild shortfall is the absence of any guidance on obtaining the id or handling a missing draft.

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

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

Schema description coverage is 100% and the single parameter 'id' is documented in-schema as the draft id. The description only echoes that with 'by id', adding no format or sourcing 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?

States a specific verb (get) and resource (a single draft) plus the retrieval key (id), which cleanly separates it from list_drafts. It does not name any sibling explicitly, but the word 'single' plus 'by id' makes the scope unambiguous.

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

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

The description contains no when-to-use or when-not-to-use guidance; it only restates the operation. The only implicit signal is that an id must already be in hand (presumably from list_drafts or create_draft), but that routing is left entirely to inference.

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

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new context: that it returns statuses, counts, and error categories only, and explicitly no imported text content, which sets expectations about output and privacy. It does not restate the permission rule (owner-only in team workspaces), so it falls short of a 5.

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

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

Content is front-loaded with the primary resource scope and the coverage is efficient in two sentences. Minor waste: the trailing 'Read-only' duplicates the readOnlyHint annotation rather than adding 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 detail is unnecessary, and the description covers the breadth of import categories well. For a read-only status tool the only notable omission is a pointer to the related verification-status sibling.

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; the schema fully documents the optional workspace selector and the owner-only read rule. The description adds no syntax or format detail about that parameter, so baseline 3 applies.

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

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

The description states a specific verb ('Read') and enumerates the exact resource scope: onboarding writing import, Substack imports, blog automation sources, and social history imports. No sibling covers the same ground (get_substack_verification_status is about verification, get_platform_analytics about metrics), so an agent can distinguish it without opening any schema.

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

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

The scope enumeration implies when this tool is relevant, but there is no explicit when-to-use/when-not statement and no named alternative for related queries like Substack verification status. Usage is inferable but not guided.

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

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

Annotations already declare this is read-only, non-destructive, and closed-world. The description adds some useful context by noting stored metric snapshots and failureCode for held notes, but it does not cover auth requirements, rate limits, or freshness beyond 'stored'; since an output schema exists, much of the return-field listing is redundant.

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

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

It is a single front-loaded sentence with no filler, starting with the core action. The long trailing enumeration of return fields is somewhat redundant given the output schema, but the description remains compact and structured.

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

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

For a two-parameter read tool with full schema coverage, annotations, and an output schema, the description is sufficient to understand what it fetches and key returned/held-note details. It is only missing explicit sibling routing guidance, which keeps it from being fully complete.

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

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

Schema coverage is 100%, so the schema already documents both id and workspace. The description only says 'by id' and adds no meaning about the workspace parameter or id format beyond what the schema provides, which matches the baseline for 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?

The description states a specific verb and resource: 'Get a single scheduled or posted note by id.' The singular, id-based scope distinguishes it from list-oriented siblings such as list_notes and list_scheduled_posts.

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

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

Usage is only implied by 'by id' and 'single ... note'; the description does not explicitly say when to use this versus list_notes, get_draft, or get_scheduled_item_readiness. It gives enough context to infer a direct lookup when an id is known, but no explicit routing guidance.

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

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

Annotations already cover the read-only/idempotent safety profile, and the description goes well beyond them: it clarifies it reads stored data and never refreshes connections, that X injects live numbers only when the token is current, and that null metrics mean 'not reported' rather than zero. These are non-obvious behaviors an agent must know.

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

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

Front-loaded with the core purpose, then layered with platform-specific caveats that each carry information. It is dense and runs long, but every sentence earns its place by disambiguating a metric or precondition.

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

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

An output schema exists, so return shape needn't be restated, yet the description still usefully explains null-vs-zero metric semantics. It covers X, Medium and Substack thoroughly; the remaining platforms get no equivalent treatment, which is the only meaningful 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?

The schema documents recentLimit but leaves platform as a bare enum. The description compensates by attaching per-platform semantics (X token dependency, Medium storage precondition, Substack benchmark and clicks ambiguity) that explain what selecting a platform actually yields, adding real meaning beyond the enum list.

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

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

States a specific verb and resource ('Read analytics for a connected platform') and immediately scopes the return ('account-level summary data where available, otherwise stored note performance and connection readiness'). This cleanly separates it from siblings like get_stats_insights and the refresh_* tools.

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

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

Gives concrete routing guidance: 'for Medium, call refresh_medium_stats first if no stats are stored' and points to refresh_substack_benchmark for benchmark freshness. It establishes clear context for when to reach for this tool versus the refreshers, though it offers no explicit exclusions or guidance for the other eight platforms.

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 real behavioral context beyond that: the distinction between the saved cadence and the effective schedule (default when nothing is saved), and the team-workspace rule that the queue belongs to the owner, so members read the owner's schedule. It does not mention rate limits or freshness, 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?

Front-loaded with the read purpose, then the operational guidance and the team-workspace caveat. Every sentence carries information, though the long parenthetical enumeration of return fields makes the first sentence dense. No filler or repetition.

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

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

With an output schema present, the description need not explain return values, yet it does so usefully; the two parameters are fully documented in the schema and the 'days' window is echoed as 'next few days'. The cross-tool handoff instruction and the team-ownership rule close the remaining gaps an agent would face.

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 a 3 is the baseline. The description goes beyond it by explaining the purpose of the returned slot values and warning that scheduledFor must be passed 'unchanged' to schedule_note, which is a semantic constraint the schema cannot express. It adds modest but genuine meaning over the schema.

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

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

The description states a specific verb (read) and resource (the writer's Note posting schedule), then enumerates exactly what is returned: saved cadence, effective schedule, timezone, next open queue slot, and open slots. This clearly distinguishes it from update_posting_schedule and list_scheduled_items, which an agent can rule out without opening any schema.

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

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

It gives explicit downstream guidance: to add a Note to the queue, pass nextOpenSlot.scheduledFor or an openSlots entry's scheduledFor unchanged to schedule_note's scheduledFor. That is a concrete use case plus the alternative tool to hand off to. It stops short of stating when not to call it (e.g., versus list_scheduled_items for already-queued items), so it is not a full 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds genuinely new operational context: the repeated-polling requirement, the guarantee that nothing is scheduled until the writer acts, and how an unanswerable question surfaces via failureMessage. That is well beyond what the structured fields convey.

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

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

Purpose is front-loaded, then polling behavior, then output interpretation. Every clause carries distinct information (cadence, stop condition, no-side-effect guarantee, failure channel) with no filler.

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

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

Even though an output schema exists (so return values need not be explained), the description supplies the interpretive frame — what done, answer, noteIdeas and failureMessage mean for the caller's next action. Nothing needed to invoke and act on this tool is missing.

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

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

Schema coverage is 100%, so runId's provenance and workspace's account-selection semantics are already documented in the schema. The description only alludes to runId indirectly and says nothing extra about workspace, so it does not add meaning beyond the schema — baseline 3 applies.

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

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

States a specific verb and resource ('Check on a Research Desk question') and ties it to the exact originating tool, start_research_desk_question, so it is unmistakable against the many other get_* siblings. The polling nature of the tool is clear from the first sentence.

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

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

Gives an explicit polling cadence (every 10 to 20 seconds), the loop exit condition (done becomes true), and an explicit exclusion ('do not start a new question meanwhile'). This is exactly the when/when-not guidance an agent needs for an async job.

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/openWorld=false, so the safety profile is covered. The description adds real value beyond them: it states the tool uses stored evidence and does not contact a provider, and it warns that Article draft content is local rather than a provider-verified copy. It stops short of describing failure modes or staleness beyond that caveat.

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

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

Three sentences, front-loaded with the operation and its key constraint, then return fields, then a caveat. The long comma-separated return-field list is somewhat dense but each clause is informative given the output 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?

With an output schema present, the description needn't enumerate returns, yet it helpfully orients the reader. Annotations cover the safety profile and the provider-contact caveat is disclosed. The main gap is the undocumented required 'id' parameter.

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

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

Schema description coverage is 0% for both parameters. The description implies the kind dimension via 'Note or Article' (matching the kind enum) but never explains the required 'id' — what it identifies or its format — so it does not fully 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 ('Inspect') and resource ('one scheduled Note or Article'), with the scope 'readiness' anchored to stored Narrareach evidence. The singular framing implicitly contrasts with the plural sibling list_scheduled_items, though no sibling is named explicitly.

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

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

There is no explicit when-to-use guidance or alternatives; the only conditional is 'without contacting a provider,' which describes execution rather than selection. An agent gets no signal about when to prefer this over get_draft, get_note, or list_scheduled_items.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: it reads only what Narrareach has persisted and does not live-refresh platform connections, and it scopes itself to the personal account.

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 dense paragraph, but front-loaded with the verb+resource and the field inventory that an agent needs. The enumeration of every platform (Substack, LinkedIn, Instagram, Threads, Facebook, TikTok, Pinterest, X) is longer than strictly necessary, though it is informative rather than filler.

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

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

An output schema exists, so return shape need not be described. The description covers scope, the mutation alternative, the stored-vs-live distinction, and the personal-account limitation, leaving no meaningful gap for a parameterless 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?

The tool takes zero parameters and the schema confirms an empty object, so there is nothing for the description to disambiguate. The baseline for a parameterless tool 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 ("the writer's main Narrareach Settings") and then enumerates exactly what is included: preferences, per-platform default accounts, connection health, and email notification settings. It clearly distinguishes itself from update_settings, the sibling that mutates the same resource.

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

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

Explicitly routes mutation to the alternative ("Change preferences with update_settings") and states a boundary condition ("Reads what Narrareach has stored; it does not refresh connections with any platform"), which implicitly points at the refresh_* siblings. It does not, however, spell out when a caller should prefer this over adjacent read tools like get_user_profile.

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, idempotentHint, and destructiveHint=false, and the description's 'reads stored, does not live-fetch' is consistent with openWorldHint=false. It adds genuinely non-structured behavior: team members see only their assigned publication and no ARR or account-wide fields, while the owner sees ARR and Medium earnings. That authorization/field-visibility disclosure is the kind of context annotations cannot carry. It stops short of describing freshness/lag of the stored series.

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 that are dense but front-loaded: payload first, data-source caveat second, permission boundaries last. The long metric enumeration is load-bearing in an output-schema world but is on the edge of redundancy given the 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?

An output schema exists, so return values need not be explained, yet the description still lists them; the more valuable coverage is the scope/permission statement (owner vs team, no ARR for team members), which nothing else provides. For a zero-required-param read tool this is close to complete, with only data-freshness/lag left unstated.

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

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

Schema description coverage is 100%, with days, workspace, and publicationId all documented in the schema (including the 365 maximum and defaults), so the baseline is 3. The description's 'for a period' loosely maps to days and 'their assigned publication' reinforces publicationId, but it adds no syntax, format, or interaction 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 and resource — 'Read the stored daily audience series' — and enumerates the exact metrics returned, which is far more specific than a restatement of the title. It does not name or differentiate itself from close siblings such as get_stats_insights, get_audience_overview, or get_platform_analytics, so an agent must infer the boundary from content rather than being told.

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

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

'Reads what Narrareach has stored; it does not live-fetch Substack' implicitly tells the agent this is the cached/reporting path and nudges fresh-data needs toward refresh_* tools, but it never names an alternative or states a when-not condition. The permission scoping sentence is context, not selection guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower, yet the description still adds value: it states the operation is non-mutating, discloses the owner-only authorization constraint, and tells the agent not to trigger a redundant code request. It does not describe rate limits or latency, but for a read-only status probe that is minor.

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

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

Three tightly written sentences with zero filler; the core read purpose is front-loaded and the exclusions plus the follow-up instruction are ordered by importance.

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

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

An output schema exists, so return values need not be described, and the description covers the key non-obvious behaviors (owner-only access, no side effects, do-not-resend-code). What remains unspecified is minor, e.g. the relationship between the check and the subsequent complete_substack_verification step.

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 connectionId and scheduledPostId are already documented in the schema, including where to source them and what scheduledPostId does. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (read) and resource (Substack verification status) with two precise sub-questions: whether a code is needed and whether a request is waiting. It explicitly disambiguates from the sibling mutation tools (start_substack_verification, cancel_substack_verification, complete_substack_verification) by declaring what it does NOT do: request a code, change the connection, or publish.

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

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

Gives concrete operational guidance: only the account owner may check, and if a code is waiting, ask for it in a normal chat message rather than sending another code. It does not name the alternative tool (start_substack_verification) for requesting a code, so the routing is implied rather than explicit.

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

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

Annotations only declare readOnly=false, idempotent=true, destructive=false; the description goes far beyond by disclosing cache reuse, that cached results don't consume allowance, per-source quota refusal rules, midnight-UTC reset, plan gating (Revenue Writer+), and that a call costs five rate-limit requests. It also explains the asynchronous processing contract (status processing + transcriptId).

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

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

Front-loaded with purpose and accepted sources, and almost every sentence carries distinct operational information (async flow, cache, quota, rate limit). It is dense — the quota/plan/rate-limit tail is a long run-on that could be split for scanability, which keeps it from a 5.

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

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

For a 4-parameter tool with an output schema, the description supplies everything an agent needs: input acceptance rules, the async polling path, failure modes (Spotify, exhausted allowance), and cost/plan constraints. Nothing material is left to inference.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning on top by explaining the url/uploadUrl exclusivity in operational terms and clarifying that episode defaults to the latest when omitted. It does not add anything beyond the schema for maxChars, which caps it below 5.

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

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

States a specific verb and resource ('Get the transcript') and enumerates the exact source types accepted (YouTube video, podcast RSS, Apple Podcasts link, episode page, direct audio file). The named purpose (quote, summarise, repurpose) plus the explicit handoff to get_transcript_status makes it distinguishable from every sibling at a glance.

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 covers when to use url vs uploadUrl, how episode resolution works for feeds, what to do for long audio (poll get_transcript_status every ~20s), and a hard exclusion ('Spotify links cannot be transcribed'). It also states quota-exhaustion behaviour per source type, so an agent knows which inputs will still succeed.

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), so the description must add value beyond that. It does: polling cadence, latency expectations, and the important billing note that 'reading a transcript does not use the allowance.' It briefly notes the ready-state result contains the text, though it does not describe failure/error states.

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

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

Four short sentences, front-loaded with the trigger condition before the polling guidance, and every sentence carries actionable information (trigger, cadence, duration, billing). 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-value documentation is unnecessary. The description covers the lifecycle of the poll (when to call, how often, when done) plus the quota behavior, giving the agent everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents transcriptId and maxChars fully. The description references the transcriptId's origin ('returned by get_transcript' via the sibling) but adds no syntax or semantics beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('check on a transcript') and explicitly ties it to the sibling get_transcript by describing the situation it operates on ('a transcript that get_transcript returned as processing'). An agent can distinguish it from get_transcript without opening either schema.

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

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

Explicitly states when to use it (after get_transcript reports processing), the polling cadence ('call again every 20 seconds or so'), and the expected duration ('long audio can take several minutes'), which also implies when to stop polling. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The text adds useful context that this is the *authenticated* user (auth requirement) and that workspaces are scoped "on this connection", but it mostly restates return contents that the output schema already defines.

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 the verb and resource first, followed by the field enumeration. The field list is long but each item is load-bearing information about what the profile yields, so there is no real padding.

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

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

With an output schema defining the return shape and annotations covering safety, the description only needs to orient the agent — which it does. The remaining gap is the absence of when-to-use guidance relative to adjacent read tools, which keeps it short of a 5.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. Schema coverage is 100% and additionalProperties is false, so no compensating detail is required.

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

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

Specific verb ("Get") plus a precisely scoped resource ("the authenticated Narrareach user"), and it enumerates exactly what the profile contains: name, email, timezone, plan, platforms, publications, workspaces. No sibling (e.g. get_voice_profile, list_workspaces) competes for the same job, so the agent can select this unambiguously.

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

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

Usage is only implied — the agent infers you call this to obtain the current user's identity/context. There is no statement of when to prefer it over get_voice_profile, list_workspaces, or list_social_accounts, 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, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond them: the material bank is truncated to the 30 most recent items unless "full" is passed, which tells the agent what the default result actually contains.

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

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

Two tight sentences: the first enumerates the resource contents, the second front-loads the call-before-drafting directive and the detail flag. 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?

An output schema exists, so return-shape explanation is unnecessary, and annotations carry the safety profile. What remains — when to call it and how the detail flag affects output — is covered, leaving nothing an agent needs missing.

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

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

Schema description coverage is 100%, so the schema already documents detail, writer, and workspace fully, including the 30-item cap and the "me" value. The description only restates the detail="full" behavior, adding essentially nothing the schema does not already say. 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 (writer's voice profile), then enumerates what the profile contains: sound, do/don't rules, topics, stances, real material, instructions, and example posts. This distinguishes it clearly from siblings like list_voice_examples, list_voice_changes, and update_voice_profile.

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

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

Gives an explicit, actionable trigger: "Call this before drafting or rewriting anything in the writer's voice." It does not name when-not to use it or point to sibling alternatives (e.g. list_voice_examples for examples alone), so it stops short of the 5 bar.

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 declare readOnly, idempotent and non-destructive, so the bar is lower; the description still adds real context by asserting it 'never sends a message' and by stating the owner-only and plan-gating constraints. It does not cover pagination or result limits, keeping it short of a 5.

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

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

Two sentences, front-loaded with the core purpose, and the trailing clause about read-only behavior is short and earns its place. Slightly dense with enumerated fields but no wasted text.

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

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

With an output schema present, return values need not be explained, and annotations cover the safety profile; the description supplies permission and plan prerequisites plus the overlap semantics. Only the lack of pagination/volume guidance and any sibling prioritization keeps it from a 5.

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

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

Schema description coverage is 100%, so the workspace and publicationId semantics are already fully documented in the schema, and the description adds no format or defaulting detail beyond it. Baseline 3 applies.

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

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

The description states a specific verb and resource ('List Substack's creator matches for a publication') and defines what a match actually is ('other writers whose audience overlaps'), plus enumerates the returned fields. That scope is distinct from siblings like list_notes or list_social_accounts, so an agent can route correctly without opening the schema.

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

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

It supplies prerequisites ('Workspace owner only, on a plan that includes agents') but never says when to prefer this over alternatives such as get_audience_overview or preview_audience_segment. Usage is implied by the resource name rather than contrasted with neighbors.

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 already declare this as a safe, idempotent, closed-world read, so the safety profile is covered. The description goes further by disclosing the semantics of defaultDestination and the defaultIsAmbiguous flag, including the recommended agent action, which is genuine behavioral context beyond the annotations.

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

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

Three tightly packed sentences with no filler. The core purpose leads, followed by return contents, followed by the conditional edge case — a clean front-loaded ordering.

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

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

With an output schema present, the description is not obligated to enumerate return fields, yet it still clarifies the two semantics an agent could misread (defaultDestination fallback and defaultIsAmbiguous). Nothing needed to call this correctly is missing.

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

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

Schema description coverage is 100%, so the writer and workspace parameters are fully documented in the schema; baseline 3 applies. The description adds no additional meaning about how those filters behave or what happens when they are omitted.

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

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

States a specific verb and resource ('List the connected Instagram accounts available for Notes') and immediately scopes it by naming the downstream consumer, schedule_note.instagramDestinations. The Instagram-specific naming naturally separates it from the LinkedIn/Medium destination siblings without needing to name 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?

Explains the context of use (obtaining accountId values for schedule_note.instagramDestinations) and gives an explicit conditional rule: when defaultIsAmbiguous is true, ask the writer and pass the account explicitly. It does not name alternative tools or state when not to call it, so it falls 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 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 declare readOnlyHint=false, idempotentHint=false and destructiveHint=true, and the description's 'Refresh' wording is consistent with a non-read-only operation. It also adds useful return context (accountId, organizationUrn, default destination). However, the surprising destructiveHint=true for a list-style tool is never explained, nor are auth/workspace 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?

Two sentences, zero filler, with the scope and the return payload front-loaded. Nothing in the text is redundant or wasteful.

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

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

An output schema exists, so return fields need not be restated, yet the description is otherwise thin on behavior for a tool whose annotations flag it as destructive and non-idempotent. The unexplained destructive hint leaves a real gap for an agent deciding whether to call it.

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

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

Schema description coverage is 100%, so both the optional writer and workspace parameters are already documented in the schema. The description adds nothing about these parameters, which is acceptable given the schema coverage but yields only the baseline.

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

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

States a specific verb pair (refresh and list) and resource (LinkedIn personal profiles and Company Pages), and scopes it with 'available for Notes', which implicitly separates it from list_linkedin_article_destinations. It does not name any sibling explicitly, so it stops short of a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no reference to the nearest alternatives (list_linkedin_article_destinations, list_social_accounts). An agent must infer that this is the pre-scheduling lookup for LinkedIn notes rather than being told.

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 only declare readOnly/no-destructive, so the description carries most of the behavioral load and does so well: it discloses that scheduled, failed and posted notes are all returned, that metrics are a stored snapshot, that unreported metrics are null rather than 0, the sort direction per status, and cursor pagination. It stops short of stating freshness guarantees or auth/rate-limit behavior.

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

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

Purpose and scope are front-loaded, but the middle is a dense run-on about output fields (socialAccountId, failureCode, platformMetrics, tags) that duplicates an existing output schema, plus a cursor-pagination sentence the schema already covers. Several sentences do not earn their place against the structured fields.

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

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

For a 10-parameter read-only list tool, the description covers scope, filtering, ordering and pagination adequately, and an output schema exists so return values need not be explained. The main gap is guidance on choosing this tool over the other list_* tools.

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

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

Schema coverage is 80%, so the baseline is 3. The description largely restates what the schema already says (from/to meaning by status, page.nextCursor, workspace absence selecting the personal account, writer requiring a workspace) and adds only the ordering rule, which is not parameter semantics.

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

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

States a specific verb and resource ("List the user's notes") and adds scope that separates it from nearby siblings: notes across every supported platform, including scheduled/failed/posted, and only those sent through Narrareach. It never names a sibling (list_scheduled_items, list_social_posts, get_note) to route the agent, so differentiation is inferential rather than explicit.

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

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

Usage is implied through the status/platform/tag/query filters and the ordering rule, which hint at when this tool applies. There is no explicit when-to-use, when-not-to-use, or alternative named among the many list_* siblings, so an agent must infer the boundary itself.

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