Substack by Cotlet

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

Beyond the annotations, it discloses meaningful side effects: a welcome email is sent, processing happens in the background, and the call waits for owner approval by default. It does not explain duplicate handling, which matters given idempotentHint=false, leaving one behavioral gap.

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

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

The opening two sentences say the same thing twice ("Add one email... as a free subscriber" then "Adds one email as a free subscriber"), which wastes space. The later operational details are valuable and reasonably front-loaded, but the redundancy costs it.

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

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

For a one-parameter mutation with no output schema, the description covers side effects, timing, consent, and the approval gate well. The only missing piece an agent would want is the behavior on a duplicate or already-subscribed email.

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?

With a single parameter and 100% schema description coverage, the schema already defines the email argument. The description adds intent (free subscriber, consent) but no format or validation detail beyond what the schema provides, so baseline 3 applies.

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

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

The description opens with a specific verb and resource ("Add one email to your list as a free subscriber") and ties it to a concrete dashboard equivalent ("the same as Add subscribers in the dashboard"). This clearly separates it from siblings such as remove_subscriber, list_subscribers, and tag_subscribers.

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 consent rule ("Add only people who agreed to hear from you") and explains the verification path via list_subscribers, which implies when to use it. It does not, however, name an alternative tool or say what to do when the email already exists.

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

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

Adds context the annotations cannot convey: annotations flag destructiveHint=true and idempotentHint=false, and the description clarifies that only the schedule is destroyed while content survives as a draft, and that a second call on an unscheduled post errors. It stops short of describing permissions needed or the response payload.

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 outcome, then the mechanism, then the re-schedule path and the error case. Minor redundancy: 'stays as a draft' is stated twice.

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

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

For a one-parameter mutation with full annotation coverage, the description covers outcome, side effects (nothing published or emailed), recovery path, and failure mode. The only gap is that with no output schema, the return value on success is not described.

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

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

Schema coverage is 100% and the single parameter is documented in the schema ('Post ID from list_posts'), so the description carries no additional parameter burden. Baseline 3 applies since nothing extra is added or needed.

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

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

States a specific verb+resource ('Stop a scheduled post') and immediately defines the resulting state ('it stays as a draft'), which cleanly separates it from delete_post and unpublish_post in the sibling list. An agent can tell what this does without opening the schema.

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

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

Gives clear usage context and names the counter-operation ('Schedule it again with schedule_post'), plus the precondition that a post with no schedule errors. It does not explicitly contrast with delete_post or unpublish_post for the case where the user wants the post gone entirely, which is the main remaining ambiguity.

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, non-destructive), and the description adds real context beyond them: it is free, it requires the user's Cotlet API key or sign-in, and it enumerates the status fields returned. Auth and cost disclosure are exactly the kind of extra behavioral facts that earn credit here; transport/pagination is the only minor gap.

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

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

The return content is front-loaded in the first sentence, with cost and auth as short trailing clauses. It is dense but not padded; every clause (statuses, cost, auth) conveys distinct information.

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

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

For a read-only tool with annotations and no output schema, the description adequately describes what comes back (per-app access and browser-account state plus the required user step and console link) and states auth needs. The missing piece is any pointer to the related request/browser tools, but nothing essential to calling it correctly is absent.

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

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

With 100% schema description coverage and a single optional 'app' filter, the schema carries parameter meaning. The description never references the filter, so it adds nothing over the structured field; 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?

The description clearly states the resource (the apps in the user's workspace) and what is reported per app: access status, Cloud Browser account state, and next step. It does not name or distinguish itself from the closest sibling, cotlet_request_apps, so an agent must infer which one to call when it wants to request access.

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?

'Free. Needs the user's Cotlet API key or sign-in.' gives a prerequisite but not a when-to-use rule. There is no explicit routing to cotlet_request_apps (for requesting an app) or to the cotlet_browser_* tools (for acting once an app is connected), so usage is only implied.

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

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

Adds material behavior beyond the annotations: it returns URL and title, refuses certain sensitive buttons, costs credits per started minute, and the session ends on close or after three minutes of inactivity. These are exactly the side effects and constraints an agent needs before invoking a destructive, open-world click.

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

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

Front-loads the action and return value, then packs refusal rules and session economics into a few short sentences. Every sentence adds useful operational information; none is filler.

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

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

For a destructive open-world browser action with no output schema, the description still explains the return value, the refusal cases, and the session cost/lifecycle. There is no material gap an agent would need filled before calling 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 coverage is 100% and the sole parameter already documents that 'element' is the number in the current page's element list. The description reinforces that meaning but adds no format or edge-case detail beyond the schema, so baseline 3 is appropriate.

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

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

Names a specific verb ('Clicks') and resource ('link, button or other element of the current page'), and pins it to a concrete mechanism (element number in the page's element list). That is enough to distinguish it from sibling browser tools such as navigate, press, or type without opening the schema.

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

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

Gives clear operating context (current page, acting as the user) and explicit exclusions for pay/buy and account/sign-in buttons. It stops short of naming alternative browser tools for non-click actions, so it is strong but not a full when/when-not/alternatives guide.

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

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

Annotations already declare non-read-only, non-destructive, and idempotent behavior. The description adds non-obvious details: cookies are preserved, the browser goes to sleep, the per-minute charge stops, and it returns the session's minutes and credits. This is valuable context beyond what the annotations provide.

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

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

The description is two concise clauses with no wasted words, front-loading the action and then the key effects. Every sentence earns its place.

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

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

For a zero-parameter close tool with annotations covering safety, the description provides everything an agent needs: the action, state preservation, billing impact, and return values. No output schema exists, so mentioning the returned minutes and credits is appropriate and useful.

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

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

There are zero parameters, so no parameter semantics are needed. The baseline score for a tool with no parameters is 4.

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

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

The description states a specific verb and resource: 'Ends the session in the user's Substack Cloud Browser.' This clearly distinguishes it from sibling browser tools like open, navigate, and click, which all interact with an active session rather than ending it.

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 provides clear context for when to use it: to stop the per-minute charge while preserving cookies. However, it does not explicitly state when not to use it or name alternatives, leaving some inference to the agent.

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

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

Annotations already cover read-only, open-world, non-idempotent and non-destructive traits, and the description adds genuinely non-structured behaviour: a per-started-minute credit cost and an idle termination after 3 minutes or on close. It stops short of saying how failures, redirects, or non-Substack URLs are handled ('Only Substack pages open' is stated but not what happens if you pass something else).

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

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

Three tight sentences: what it does and returns first, then the domain restriction, then the cost and lifetime caveats. Nothing is redundant and the routing-relevant information is front-loaded.

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

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

No output schema exists, and the description compensates by naming the return values (final URL and title). For a one-parameter browser navigation tool with rich annotations, that is nearly complete; only error/non-Substack behaviour and the relationship to cotlet_browser_open are unaddressed.

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

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

Schema coverage is 100% and the single 'url' parameter is already documented with a format and example, so the schema does the heavy lifting. The description's 'Only Substack pages open' arguably narrows the schema's broader 'public http or https address, e.g. https://example.com', which adds a note of ambiguity rather than clarifying meaning.

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

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

It states a concrete verb ('Opens') and resource ('a public http or https address in the user's Substack Cloud Browser'), and even names what is returned. It does not, however, distinguish itself from the sibling cotlet_browser_open, leaving the agent to guess which of the two starts a browsing session.

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 an implied usage context ('Only Substack pages open') but never says when to pick this over cotlet_browser_open or when to precede it with cotlet_browser_open. The credit/expiry note hints at cost-awareness but does not route the agent to alternatives.

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

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

Goes well beyond the annotations: it discloses the cost model ('Every started minute of the session costs credits'), the session lifetime ('ends when closed or 3 minutes after the last call'), and that the user observes everything live. These are non-obvious operational constraints an agent must know before calling, and nothing here conflicts with readOnlyHint=true or openWorldHint=true.

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

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

Five short sentences, front-loaded with what the tool is, then alternatives, return values, and cost. Every sentence carries information an agent needs; there is no filler or repetition of the title.

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

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

Despite having no output schema, the description states what comes back ('returns the page's URL and title'), what triggers the session to end, and what it costs. Combined with 100% schema coverage, an agent has everything needed to call it correctly and know when to stop.

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

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

Schema coverage is 100% and the schema already explains the URI format and the app-browser case, so 'Opens `url` when given' adds only the small fact that the parameter is optional. That matches the baseline for a well-documented single parameter.

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

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

The description names a specific verb and resource ('Wakes the user's Substack Cloud Browser, a real Chrome hosted on Cotlet') and explicitly scopes it against the rest of the toolset. The distinction from cotlet_browser_navigate/click is implicit but the framing as the session-start tool is clear, and an agent can tell it apart from the plain Substack API tools 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?

'Use it for what the Substack tools do not cover' gives a clear routing rule to the agent and names the category of alternatives. It stops short of naming the follow-on browser siblings (navigate, click, read) that this call enables, so the handoff sequence 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?

Adds substantial context beyond the annotations: keyboard-level behaviours, a hard refusal rule for Enter on account pages, the return values (URL and title), and session economics (credits per started minute, idle timeout of 3 minutes). It does not explain why the operation is flagged destructive or what a keypress might trigger, so it stops short of fully covering the destructiveHint=true annotation.

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

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

Front-loaded with the core action, then key examples, then constraints and cost. Dense but every sentence carries information; the credit/session sentence is long but operationally relevant 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?

Despite having no output schema, the description states what is returned, covers the safety-relevant refusal, and discloses cost and session lifetime. An agent has everything needed to invoke this correctly in the Substack Cloud Browser context.

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 enum enumerates all 15 allowed keys, so the baseline is 3; the description earns an extra point by explaining what the most important keys actually do and by documenting a per-key constraint (Enter refused on account pages) that appears nowhere in the schema.

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

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

States a specific verb and resource ('Presses one key on the current page') and scopes it precisely to the focused element, which cleanly separates it from cotlet_browser_click and cotlet_browser_type. Concrete key-to-outcome examples (Tab to next field, Enter to send, arrows for suggestion lists) make the intent unmistakable.

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

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

Gives clear situational examples of when to press keys rather than click or type, plus an explicit exclusion ('Enter on account pages is refused'). It does not name sibling tools as alternatives, but the usage contexts are strong enough that an agent can pick correctly.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses privacy limits (field values, cookies and storage are never returned), a 20,000-character truncation cap, scroll-relative positioning on long pages, per-minute credit cost, and a 3-minute session idle timeout. These are exactly the operational facts an agent needs before calling.

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

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

Four sentences, each carrying unique information — return contents first, then exclusions, then truncation/scroll, then cost and lifetime. No repetition of the title and 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 no output schema, the description must carry the return contract, and it mostly does (text + element list, exclusions, truncation). It does not describe the element-list format (e.g. whether the numbering is directly usable as a selector for cotlet_browser_click), which is the one gap for an agent driving a browser.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter syntax to explain. The description correctly spends its words on output shape and session behavior instead.

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

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

States a specific verb and resource ('Returns the current page of the user's Substack Cloud Browser') and enumerates exactly what comes back: readable text plus a numbered list of links, buttons and fields. This clearly separates it from siblings like cotlet_browser_screenshot (pixels) and cotlet_browser_click (action).

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

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

The mention of a 'numbered list of its links, buttons and fields' implies this is how you discover what to click or type next, and the scroll note implies when the output is offset. But no explicit when-to-use statement or named alternative (e.g. screenshot vs read) is given, so usage must be inferred.

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

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

Beyond the annotations, the description discloses credit costs per started minute and the session lifecycle: it ends when closed or 3 minutes after the last call in the browser. It also specifies the return format as a JPEG of the visible page area with URL and title.

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

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

The description is short and front-loaded with what the tool returns, followed by the important cost and session-lifetime constraints. Every sentence adds operational value without unnecessary detail.

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

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

With no output schema, the description adequately explains that the tool returns a JPEG image plus URL and title, limited to the visible page area. Annotations already cover safety profile, and the description adds the critical cost and timeout behavior needed to invoke it responsibly.

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

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

There are no parameters, so parameter semantics are not a concern and the baseline is 4. The description appropriately focuses on return content and session behavior instead of 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 a specific verb and resource: it returns a JPEG image of the visible part of the current page in the user's Substack Cloud Browser, along with URL and title. It also distinguishes itself from the text-reading sibling by noting it captures boards, canvases, and layouts that page text does not show.

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

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

The phrase 'boards, canvases and layouts that the page text does not show' clearly implies when this tool is preferred over the text-reading sibling. However, it does not explicitly name cotlet_browser_read or state when not to use this screenshot tool.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations: it says the motion emulates a human mouse wheel, that lazy content becomes visible only after scrolling, that the response includes URL, title, and at_top/at_bottom, and that every started minute bills credits with the session expiring 3 minutes after the last call. That is material operational context an agent cannot get from 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 tight sentences: behavior and modes first, then the lazy-load payoff, then return value and cost model. No filler, and the most decision-relevant information is front-loaded.

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

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

There is no output schema, yet the description names the returned fields (URL, title, at_top/at_bottom) and covers the credit/session lifecycle. Combined with the fully documented 3-parameter schema and the annotations, 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% and the schema already documents element, screens (with the 0.8 default and 10 cap), and direction. The description mostly restates those in prose, though it does sketch how the modes relate (screens applies to down/up, element overrides distance). Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb (scrolls) and resource (the current page in the Substack Cloud Browser) and enumerates the exact modes: down/up by `screens`, to top/bottom, or until an element is in view. That vocabulary separates it cleanly from cotlet_browser_read, cotlet_browser_click, and cotlet_browser_navigate 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?

"Content that loads on scroll appears, and the next read lists it" gives a clear when-to-use signal: call this to trigger lazy loading before a read. It does not explicitly exclude or contrast the other browsing siblings (navigate, click, read) or say when scrolling is unnecessary, so it falls short of a full when/when-not/alternatives statement.

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 openWorldHint=true, but the description adds genuinely new context: the return value (URL and title after selection), the refusal of card fields and account pages, and the credit/session model including the 3-minute idle close. It never explains why a dropdown selection is flagged destructive, which is the one notable gap.

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

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

Three sentences, action first, with constraints and cost framing after — well front-loaded. A mild deduction for awkward phrasing ('as read lists it') and for packing three unrelated facts (return value, refusals, billing) into one trailing sentence.

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

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

With only 2 simple params and no output schema, the description covers what an agent needs: how to target the element, what comes back, what is off-limits, and the session cost model. The absence of any note on failure behavior when the element index is stale or the option label does not match keeps it from a 5.

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

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

Schema coverage is 100% so the baseline is 3, but the description goes further by clarifying that 'option' may be the label 'as read lists it (or its value)' — a distinction the schema's bare 'The option.' description does not make. The element index mapping also matches the schema without adding risk of confusion.

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 ('Chooses an option of a drop-down list on the current page') and scopes it to the user's Substack Cloud Browser, which cleanly separates it from cotlet_browser_click, cotlet_browser_type, and cotlet_browser_press. The two identifying inputs (list index, option label/value) are named in the same 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?

Use is strongly implied by the resource being a drop-down list, and a real exclusion is given ('Card fields and account pages are refused'). However, no sibling alternative is named, so an agent must infer on its own that a non-select element should go to cotlet_browser_click instead.

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

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

Annotations already flag this as non-read-only, destructive and open-world; the description adds substantial context beyond them: sensitive-field refusals, the URL and title returned after the action, per-minute credit cost, and the 3-minute idle session termination. These are exactly the operational facts an agent needs before typing.

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 purposeful — every sentence carries a distinct fact (action, return value, refusal policy, billing/lifecycle). The opening sentence is long and packs several clauses, but nothing is wasted.

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

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

With no output schema, the description covers the return value (URL and title), the refusal boundary, and the session/credit lifecycle. Nothing needed to invoke the tool safely 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, but the description adds meaning: `element` is the field's number in the rendered element list, not a CSS selector, and `submit` means Enter is pressed (e.g. to search). That resolves the main ambiguity in how to address a field.

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

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

States a specific verb and resource (types text into a field of the current page in the Substack Cloud Browser), plus the addressing mechanism (element number in the page's element list). It is clearly differentiated from siblings like cotlet_browser_click, cotlet_browser_press and cotlet_browser_select.

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 rules out password, card, one-time-code fields and sign-in pages, telling the agent that those must be left to the user. It also explains that `submit` presses Enter, which disambiguates from cotlet_browser_press. It does not, however, state when to prefer press/click/select over type beyond that hint.

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

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

Annotations already flag destructive, openWorld and non-idempotent; the description adds value beyond them by disclosing the return payload (URL and title) and the cost/lifecycle model (credits per started minute, session closes or ends 3 minutes after the last call). It does not explain what the destructive hint means in practice, such as whether an existing file is replaced.

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

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

Three dense sentences with the action and target front-loaded, followed by input format, limits and cost. Every sentence carries information; no repetition of the schema's property text.

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

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

No output schema exists, yet the description still names the return values, and it covers input limits, accepted formats, and billing/session behavior. An agent has everything needed to decide to call and to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description earns one extra by supplying the 20 MB per-file cap, which the schema does not state, and by concretely illustrating both accepted file object shapes. Element addressing is left to the schema.

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

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

States a specific verb (puts files into) and precise resource and target: a file field on the current page of the Substack Cloud Browser, or the picker an upload button opens. The browser context distinguishes it from the sibling cotlet_upload_file, though the relationship is only implied via the file_id mention 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?

Explains the two concrete situations that select this tool: targeting an existing file input element, or triggering an upload-button picker. It implies the cotlet_upload_file prerequisite for file_id without naming it as an explicit alternative path.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes the status vocabulary and the polling context, but says nothing about behavior for an unknown or expired call_id, retention window, or whether repeated polling is rate-limited.

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

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

Two short sentences, front-loaded with the resource and key, with the status set inlined rather than padded into separate sentences. The trailing 'answered with status pending or running' is slightly awkward phrasing but earns its place as scoping information.

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

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

For a one-parameter read tool with no output schema, the description supplies the crucial return-value information (the full status enum) that the structured fields omit. Only minor gaps remain, such as what accompanies the status in the response.

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 required parameter with 100% schema description coverage, so the schema already carries the semantics. The description's 'by its call_id' merely restates the schema and adds no format or sourcing detail (e.g. where the call_id came from).

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 resource (an earlier Cotlet call) and a specific retrieval (its status, keyed by call_id), and enumerates every terminal and intermediate state so the agent knows exactly what it will get back. No sibling tool overlaps this resource, so the lack of an explicit 'not for X' does not create ambiguity.

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

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

The closing clause scopes it to calls whose prior response was pending or running, which effectively tells the agent this is a polling tool rather than a general history lookup. It stops short of naming an alternative or saying what to do once a terminal status is reached.

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

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent write, so the description only needs to add context. It does: it states where the report goes, that error text and call_id are attached when available, that secrets are never included, and that an API key or sign-in is required. It does not mention what happens on duplicate submissions, consistent with idempotentHint=false but not explained.

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

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

Three dense sentences, front-loaded with the action and its goal, then the trigger scenarios, then the content and auth constraints. No filler and nothing repeated from the title or annotations.

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

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

For a mutation tool with no output schema, the description covers purpose, triggers, attached payload, secret handling and authentication, which is enough to call it correctly. It omits what the caller receives back or whether filing duplicates creates separate reports, a minor gap for a write 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 100%, so enum values for `kind` and field meanings for `tool`, `app` and `call_id` are already documented in the schema. The description adds only marginal meaning, clarifying that call_id and error text are picked up automatically when present, which is the baseline expectation given full schema documentation.

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

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

The description names a specific verb and resource ('Sends a report straight to the Cotlet team') and enumerates the concrete situations it covers: failed or wrong-data tools, blockers, missing tools/fields/apps. It stops short of explicitly distinguishing itself from the sibling cotlet_request_apps, which plausibly overlaps with the 'app the task needed and Cotlet lacks' case.

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

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

Clear contextual triggers are given ('failed or returned wrong data', 'an error you could not get past', 'needed and Cotlet lacks'), which is enough for an agent to decide when to file a report. It offers no explicit exclusion or pointer to cotlet_request_apps / cotlet_get_call, so edge-case routing is left to inference.

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

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

Adds substantial behavior beyond the annotations: a live app is granted immediately, other requests go to the Cotlet team with a 72-hour response window, the operation is free, and authentication via Cotlet API key or sign-in is required. The mutation-like but non-destructive nature is consistent with 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 tight sentences with the core action front-loaded, followed by outcome behavior, slug source, cost, and authentication. No wasted words.

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

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

For a simple one-parameter request tool with no output schema, the description provides everything needed to call it correctly: what it does, how outcomes differ, where to get valid slugs, and what credentials are required.

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 the apps parameter and slug examples. The description adds useful context by pointing to https://cotlet.dev/api/v1/apps as the canonical slug list, though it does not mention the maxItems limit.

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: request access to apps for the user's workspace. It distinguishes this from informational siblings like cotlet_apps and cotlet_balance by describing an action that submits an access request and explains the two possible outcomes.

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 clearly frames the tool as the programmatic equivalent of 'Request access' in the console, which implies when to use it. It does not explicitly say to use cotlet_apps first to discover slugs, so a small inference remains.

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

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

The description adds substantial behavioral detail beyond the annotations: it returns a one-time upload_url and file_id, requires an HTTP PUT to upload_url, enforces a 25 MB limit, states the URL works only once, and notes the Cotlet API key/sign-in requirement. These details are consistent with the non-read-only, non-destructive annotation profile and materially help the agent understand the workflow.

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 most important fact—what is returned and how it is used—is front-loaded in the first sentence. The remaining sentences cover upload method, size limit, one-time behavior, and auth without wasted words.

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

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

There is no output schema, and the description fully explains the return values, the upload workflow, the file size constraint, one-time URL behavior, and authentication needs. An agent has enough information to invoke and chain this tool correctly.

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

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

Schema description coverage is 100%, with both name and content_type documented with examples in the schema itself. The description does not add parameter-specific syntax or constraints beyond that, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: it returns a one-time upload_url and file_id for a local file. It also clarifies the intended use cases (an image for a post, an attachment), but it does not explicitly distinguish this helper from sibling tools such as cotlet_browser_upload.

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 clear usage context: call this to obtain upload_url and file_id, PUT the file to upload_url, then pass file_id to any argument that accepts a file. It does not name when-not-to-use cases or alternative tools, so it falls short of the top score.

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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds genuine value beyond them: it declares the call is credit-free ('Free') and that authentication via the user's Cotlet API key or sign-in is required, which matters for failure handling. It does not say what shape/format the response takes, but the field list largely compensates.

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: the first front-loads the substantive return contents, the second carries the cost and auth facts. No filler, no restatement of the title, and 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?

There is no output schema, so the description must carry the return contract — and it does, enumerating each field the agent will receive. Combined with the required-auth note, an agent has enough to call it correctly. Only minor gaps remain, such as how failures look when the key is missing or what access-status values are possible.

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 and the baseline of 4 applies. Nothing in the text conflicts with the empty schema.

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

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

The description names a concrete resource — the Cotlet account identity for this connection — and enumerates exactly what comes back (email, workspace, access status, API key/OAuth client scope, callable apps, credit balance). That is far more specific than the bare 'who am I' title. It stops short of explicitly distinguishing itself from siblings like cotlet_balance and cotlet_apps, which overlap on the balance and app-list portions of the response.

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 context is implied rather than stated: an agent can infer this is the pre-flight identity/permission check, and 'Needs the user's Cotlet API key or sign-in' plus 'Free' tells it the prerequisites and that no credits are consumed. However there is no explicit 'call this before cotlet_apps or cotlet_balance to verify access' routing, and no stated conditions under which this tool should be skipped.

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

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

Adds real context beyond the annotations: nothing is sent until publish/schedule, the draft reaches no one, so it 'runs without asking', and it returns post_id plus editor link. It does not address the destructiveHint=true annotation (e.g. that an existing draft could be overwritten or deleted later), which is the one behavioral gap.

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

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

Front-loaded with purpose and the 'nothing is sent yet' constraint, then the Markdown capability list, then the sibling routing. Dense and mostly waste-free, though the long inline Markdown enumeration makes it slightly heavy for a single paragraph.

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

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

Covers everything an agent needs for a 4-parameter tool with no output schema: what it creates, that it is non-sending, what it returns, accepted content format, and where to go next. No return-shape explanation is required since the description names the two returned fields.

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, but the description goes further by detailing exactly which Markdown constructs body_markdown accepts (headings, lists, quotes, code blocks, rules, images by public URL, inline formatting) and that images must be public URLs. That is meaning the schema does not carry.

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

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

States a specific verb and resource ('Creates a draft in your publication') plus the return values (post_id, editor link). It explicitly separates itself from publish_post and schedule_post, so an agent can distinguish it from the sending siblings without opening any schema.

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

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

Explicit when-to-use and when-to-use-something-else: 'Sending is a separate step: schedule_post or publish_post.' It also gives the pre-condition that content arrives as Markdown and the exclusion that local image files cannot be used, which prevents a common failed 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?

Adds useful server-side behavior the annotations don't: the slug is derived from the name, and an empty tag is not surfaced anywhere. However, annotations flag idempotentHint=false and destructiveHint=true, and the description never warns that repeat calls create duplicate tags or says what gets affected — the highest-value behavioral disclosure for this tool is missing.

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 clauses with no filler; the core action leads. The opening fragment 'New tag for grouping your posts.' is slightly awkward but still informative rather than wasteful.

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

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

For a single-required-param create tool with no output schema, the essentials are present, but the agent cannot tell what the call returns (the tag object, its slug, or its id) for use in a follow-up tag_post call, and duplicate-creation behavior is unaddressed.

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

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

Schema coverage is 100%, so baseline is 3, but the description earns extra credit by explaining that the slug is generated from name — telling the agent there is no separate slug input and that name choices propagate into URL identifiers. The example in the schema already covers format, so it isn't a 5.

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

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

States a specific verb and resource: 'Creates a post tag on your publication', and the phrase 'post tag' separates it from the sibling create_subscriber_tag. It goes beyond the title by explaining grouping semantics, though it never names a sibling outright.

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?

'Put posts under it with tag_post' gives a concrete next step and the condition under which the tag becomes meaningful, and 'A tag with no posts shows nowhere' tells the agent an empty tag is harmless but invisible. No explicit exclusions or comparison to other tag tools, 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=false and destructiveHint=true, so the safety profile is given. The description adds genuinely new behavioral context — that tags are private and invisible to subscribers — but says nothing about name uniqueness, what happens if a tag with the same name exists, or how the destructive hint manifests.

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 resource and purpose, then the privacy trait, then the follow-up action — a sensible ordering. The word "private" is stated twice ("private tag" and "Tags are private"), a minor redundancy in an otherwise tight four-sentence description.

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

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

For a one-parameter create tool with full schema coverage and annotations, the description supplies the two things structured data cannot: the privacy semantics and the tag_subscribers follow-up. Return value is unspecified, but with no output schema and a trivial operation that is a minor gap rather than a blocker.

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 required parameter and the schema documents it fully with an example ("Tag name, e.g. Early readers"). The description adds no format, length, or uniqueness constraints beyond the schema, which is acceptable at 100% coverage but leaves it at 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 and resource ("Creates a subscriber tag on your publication") plus the scope "private tag for grouping subscribers," which separates it from create_post_tag and from list_subscriber_tags. It stops short of explicitly naming the post-tag sibling, so an agent must infer the distinction from context.

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?

"Put subscribers under it with tag_subscribers" gives clear downstream workflow and implicitly tells the agent this is the prerequisite step in a two-call sequence. It does not state exclusions (e.g., when to prefer create_post_tag or how it relates to list_subscriber_tags), so it is strong but not exhaustive.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds real substance on top: replies by others survive under a deleted placeholder, foreign comments produce an error rather than a silent failure, and calls are gated behind an owner approval step that can be disabled. It stops short of saying whether the deletion is reversible or what the call returns, which is the only remaining behavioral gap.

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

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

The lead sentence and the follow-up 'Deletes something you wrote: ...' restate the same scope twice before reaching new information. The valuable content (placeholder behavior, error case, approval gate) is present but arrives after redundant framing.

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

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

For a single-parameter destructive tool with annotations already covering the safety profile, the description covers the critical unknowns: what survives deletion, what fails, and the approval requirement. Only the return value is unexplained, and with no output schema that is a minor omission.

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

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

Schema coverage is 100% for the single comment_id parameter, so the schema already carries the description. The description only adds the constraint that the ID must reference the caller's own content, otherwise the error case applies. Baseline 3 is appropriate 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 (delete) and three specific resources (comment, Note, Note reply), and explicitly scopes it to content the caller authored. It also distinguishes itself from the sibling remove_comment by naming it alongside the condition that selects it.

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

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

Gives both when-to-use and when-not-to-use: someone else's comment errors out, and removing your own comment on your own post should use remove_comment instead. The alternative and its trigger condition are named explicitly rather than left to inference.

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

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

Beyond the destructiveHint annotation, the description discloses concrete consequences: comments and stats are removed, a scheduled send is cancelled, published content disappears from web/archive/app, already-sent emails remain, and there is no undo. These are exactly the behavioral details an agent needs before calling a destructive tool.

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

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

The description is front-loaded with the action and consequences, and every sentence carries useful information. It is slightly repetitive in restating the draft/scheduled/published triad twice, which keeps it from a perfect score.

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

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

For a destructive, non-idempotent, open-world mutation with no output schema, the description covers scope, side effects, irreversibility, confirmation behavior, and the sibling alternative. Nothing an agent needs in order to call it safely is missing.

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

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

Schema coverage is 100%, so the single post_id parameter is already fully documented in the schema. The description adds only that deletion targets one post of your publication, which is minimal additional semantic value. Baseline 3 is appropriate 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?

The description gives a specific verb (delete) and resource (post), and explicitly enumerates the three post states it handles: draft, scheduled, and published. It also names the sibling tool unpublish_post as the alternative, so an agent can distinguish the two without opening either schema.

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

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

It states exactly when to use this tool versus the closest sibling, noting that unpublish_post keeps the post as a draft instead. It also explains the confirmation default and that the owner must approve, which informs invocation conditions.

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, non-idempotent, and open-world, so the description does not need to re-state the safety profile. It adds genuinely useful behavior: the new item is always a draft, Substack prepends [COPY] to the title, and nothing is published or sent. That last point reassures without contradicting the destructive annotation, which correctly reflects that a new resource is created.

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

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

Three short sentences, front-loaded with the core action, followed by field scope and the one surprising behavior ([COPY] prefix). Every sentence carries information the agent would otherwise have to discover by trial.

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

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

For a simple one-parameter mutation with no output schema, the description is complete: it covers what is produced, which fields are copied, the title side effect, the follow-up tool for renaming, and the non-publication guarantee.

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 single parameter has 100% schema coverage and is documented there as the post ID from list_posts. The description names no parameters and adds no syntax or format beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Copy any post into a new draft') and distinguishes the result from a blank draft by describing exactly which fields carry over. An agent can tell this apart from create_draft 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?

Clear context: use this to replicate an existing draft or published post, with an explicit follow-up pointer to update_draft for renaming. It does not explicitly say when to prefer create_draft instead, but the copy semantics make the boundary obvious.

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?

Although annotations already mark this as read-only, idempotent, and non-destructive, the description adds important behavior: background CSV generation, a wait of about a minute, possible retry request, and a sign-in-free link that expires after 24 hours.

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

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

The description is front-loaded with the primary outcome and uses each sentence to add distinct value: CSV contents, wait behavior, link expiry, and the filtered alternative. There is no redundant restatement of the tool name or annotations.

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

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

With no output schema, the description still explains the returned artifact: a CSV download link, row count, included columns, and link expiry. It also covers the background build and retry behavior, leaving no important operational gap for this zero-parameter export 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 has zero parameters, so there is no parameter meaning to clarify. The baseline for a zero-parameter tool is 4, and the description does not need to compensate for missing input metadata.

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

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

The description states a specific action and resource: exports the full subscriber list as a CSV download link with row count. It also distinguishes this from filtered list retrieval by naming list_subscribers as the alternative.

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

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

It explicitly says to use list_subscribers for filtered pages, which defines when this tool is and is not appropriate. It also explains the wait behavior and what to do if the export is not ready.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true. The description adds real context beyond them — the social visibility ('They see the follow') — but never explains what unfollow destroys or whether it notifies the person, leaving the destructive profile under-described 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?

The lead sentence is well front-loaded, but the second sentence ('Follows a person on Substack, as Follow on their profile does, or unfollows them') largely restates the first. The subscribe-versus-follow clarification earns its place; the rest is padding.

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

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

For a two-parameter mutation with full schema coverage, no output schema, and annotations supplying the safety profile, the description covers purpose, the follow/subscribe distinction, and the social side effect. Only the reversibility and notification semantics of unfollow are left implicit.

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

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

Schema coverage is 100%, so both `user` (handle or ID) and `unfollow` (default false) are fully documented in the schema. The description only restates the unfollow toggle conceptually and adds no format, handle-vs-ID, or edge-case guidance beyond that 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 (follow/unfollow) and resource (Substack user) with the effect ('so their Notes reach your feed'). It also pre-empts confusion with the adjacent concept of subscribing, so an agent can distinguish this from add_subscriber without further reading.

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

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

Gives clear conditions: use to follow a person the way the profile Follow button does, use the `unfollow` flag to reverse it, and explicitly rules out newsletter subscription. No sibling tool is named as an alternative, which is the only gap.

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

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

Annotations already establish this as a safe, read-only, idempotent operation. The description adds useful behavioral context beyond the annotations: Substack computes the data in the background, and a new publication may show empty lists for a while.

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

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

The description is front-loaded with the core purpose and then enumerates the returned data. It is dense but well structured, and every clause contributes useful selection or interpretation context.

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

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

There is no output schema, so the description must explain return values, and it does: subscriber counts by geography, total country/state counts, and overlapping publications. It also covers the important caveat about delayed computation for new publications.

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 parameters and defaults. The description still adds value by giving ISO code examples such as us, gb, ny, and ca, and by clarifying that paid_only restricts counts to paid subscribers.

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: returns audience insights about where subscribers live and which publications share readers. It distinguishes this from sibling analytics tools by naming the exact dimensions returned: subscriber counts by country or US state, paid/all counts, countries/states with subscribers, and overlapping publications.

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 makes the usage context clear by locating the data under Analytics > Statistics > Audience and explaining both region modes. It does not explicitly name alternatives such as get_publication_stats or list_subscribers, but the scope is clear enough for an agent to choose it for geographic audience and overlap data.

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. The description adds a genuinely useful behavioral detail beyond that: 'Opening a conversation this way marks nothing read,' which tells an agent this read has no side effect on unread state.

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?

Reasonably front-loaded, but 'oldest first' is repeated twice and 'latest messages' appears in both sentences, making it feel redundant rather than crisp.

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

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

With no output schema, the description steps up to describe the return payload: who is in the conversation, messages with sender, text and time, in order. That is sufficient for an agent to know what it gets back.

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

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

Schema coverage is 100% and already documents conversation_id as coming from list_conversations. The description adds no parameter detail beyond the schema, so the 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: retrieves the latest messages of one direct-message conversation. It implicitly distinguishes from list_conversations by emphasizing 'one' conversation, though it never names the sibling explicitly.

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

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

Usage is implied (open one conversation to view its messages), and the schema points to list_conversations for the ID. But the description gives no explicit when-to-use versus alternatives or when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety bar is lower. The description still adds genuinely useful behavior: one row per calendar day, null where data is missing, and the start-day rule for young publications, which the agent cannot infer from the schema.

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

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

Front-loads the key fields ('Day by day: total and paid subscribers, followers and views'), which is good. The subsequent sentence is clunky and overloaded ('as the charts on the dashboard home and in Audience') and could be tightened without losing information.

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

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

With a single optional parameter and no output schema, the description does the necessary work of describing the return shape: one row per day, the fields returned, and null semantics. It is largely complete for a simple read tool, with only the row/site-vs-app granularity left slightly ambiguous.

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

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

Schema coverage is 100% with a single enum parameter and a documented default, so the schema carries the parameter semantics. The description adds no format or semantics for 'period' beyond what the schema already says, so baseline 3 applies.

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

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

States a specific verb-driven purpose: per-day total and paid subscribers, followers, and views, one row per day. It is clearly a daily time-series stats tool distinguishable from sibling stats tools, 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?

Usage is implied by 'Day by day' and the reference to dashboard charts, giving an agent a sense of when this applies versus a snapshot tool. However, it never states when to prefer get_publication_stats, get_audience_insights, or get_post_stats, so routing is left to inference.

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

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

Adds real behavior beyond the annotations: 'Reading marks nothing seen' clarifies no read-state side effects, 'Page with next_cursor' documents pagination, and 'the feed is personal and changes between calls' warns results are volatile and not cacheable. That last clause sits in mild tension with idempotentHint=true, though it describes result variance rather than side effects, so it is not a true 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?

The scope and return shape are front-loaded in the first two sentences, followed by tab semantics, exclusions, and pagination. Nearly every sentence carries information, though the opening fragment ('posts and Notes, For you or Following') is slightly clipped and the capitalization is inconsistent.

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-optional-param read tool with no output schema, the description covers the return shape ('split into posts and Notes in feed order'), pagination, exclusions, and volatility. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by defining what each tab value actually contains and how cursor paging works ('Page with next_cursor'). It adds semantic meaning over the enum labels 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 and resource ('Returns one page of the home feed of the Substack app') and scopes it to posts and Notes, which separates it from list_notes, list_posts, and list_activity. An agent can identify the resource and its two-variant scope 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?

Explains the two modes clearly ('for_you is Substack's own mix; following holds only people and publications you follow') and notes that follow suggestions are excluded, so the agent knows what it will and won't get. It stops short of naming an explicit alternative (e.g. use list_notes for note-only browsing), so there is no routing statement beyond scope.

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?

Although annotations already declare this as a read-only, idempotent, non-destructive operation, the description adds important behavioral details: full Markdown body including paywalled content, images as URLs, lossy conversion of buttons/embeds/footnotes, and publish_at for scheduled posts. These are exactly the kind of data-shape and lossiness caveats an agent needs.

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 definition is front-loaded and mostly efficient, starting with the returned fields and then adding caveats. There is minor redundancy in repeating that the full body is Markdown and that it returns one post, but no sentence is wasted.

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

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

There is no output schema, so the description bears responsibility for explaining return values. It does so thoroughly, covering fields, Markdown body, paywall inclusion, image handling, unsupported rich elements, and scheduled-post metadata, making the tool complete enough to invoke correctly.

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

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

The schema has 100% description coverage for the single post_id parameter, including that it comes from list_posts. The description does not add further meaning about the parameter, so the schema does the heavy lifting; a 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?

The description uses a specific verb and resource, stating it returns one full post from the publication, whether draft, scheduled, or published. It clearly distinguishes this from list-oriented siblings like list_posts and metrics siblings like get_post_stats by emphasizing the complete body and metadata of a single post.

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

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

The description gives a clear context for use: retrieving a full post, including body content and paywalled parts. It also warns that writing the body back via update_draft will drop buttons, embeds, and footnotes, but it does not explicitly say when to choose list_posts or other sibling tools instead.

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 the read-only, idempotent, closed-world profile, so the bar is lower. The description adds genuinely useful context beyond that: email addresses are never returned (privacy boundary) and counts keep changing for days after a send (eventual consistency), which affects how an agent should interpret and re-query results.

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

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

Front-loaded with the core answer, then a sentence expanding the return contents, then a caveat about freshness. Mostly tight, though the opening phrase 'the subscribers it won and lost' is re-specified in the next sentence, costing a little 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 no output schema, the description carries the burden of explaining return values and does so thoroughly, including privacy scope and freshness caveats. What remains unclear is only how this relates to sibling stats tools, a minor gap for a single-parameter read.

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

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

Only one parameter and schema description coverage is 100%; the schema already explains post_id comes from list_posts. The description adds no format or sourcing detail beyond that, so the baseline of 3 applies.

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

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

States a specific resource and enumerates exactly what is returned: likes, comments with names/handles, and signups/subscriptions/unsubscribes. 'The Engagement and Growth parts of a post's stats' implicitly carves out scope against siblings like get_post_stats and get_post_traffic, though no sibling is named directly.

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

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

Usage is implied by the division of a post's stats into parts, which suggests this tool covers engagement/growth while others cover the rest. However, there is no explicit when-to-use or when-not-to-use statement naming an alternative tool.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds meaningful behavioral context beyond that: drafts/scheduled posts error, stats grow over days, email numbers cover the send, views include web, and likes are reactions. It does not cover auth or rate limits, but adds substantial value.

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

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

The description is compact and front-loaded with the returned metrics, then adds scope, metric definitions, error behavior, and a timing caveat. Every sentence earns its place without repetition or waste.

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

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

There is no output schema, so the description carries the burden of explaining return content; it names the metrics and their meanings. It also covers the draft/scheduled error case and liveness of the numbers. It does not describe the exact response structure, but it is otherwise complete for a simple read-only stats 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 100%, and the schema already documents post_id as coming from list_posts. The description adds only that the post must be published, which is useful but not additional parameter-level detail.

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: returns engagement numbers for one published post. It lists concrete metrics and clarifies scope with 'as on its stats page in the dashboard.' It is clear but does not explicitly distinguish itself from siblings such as get_post_engagement or get_post_traffic.

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 useful context that drafts and scheduled posts return an error, and that numbers keep growing after a send. However, it does not say when to use this tool instead of related tools like get_post_engagement or get_post_traffic, so guidance 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 already declare readOnly, idempotent, closed-world and non-destructive behavior, so the safety profile is covered. The description adds real value beyond that by enumerating the returned breakdowns (views, share of all views, free and paid subscribers per source, plus category and device shares) and by disclosing the empty-list behavior — the latter is a genuine behavioral trait not in any structured field.

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

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

Three short sentences, front-loaded with the core definition, then the return shape, then the edge case. No filler and nothing repeated from the schema or annotations.

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

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

With no output schema, the description carries the burden of describing return values and does so comprehensively, including the empty-state case. It does not say whether traffic is scoped to a time window or lifetime totals, which is the one thing an agent might still wonder about before calling.

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 required parameter and schema coverage is 100%, with the schema itself explaining 'Post ID from list_posts.' The description adds nothing further about the parameter, 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 resource and dimension ('Where a post's readers came from: sources, categories and devices') and names what it returns ('the Traffic part of a post's stats'). This implicitly separates it from get_post_stats and get_post_engagement, but it never names those siblings explicitly, leaving the agent to infer the split.

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 makes it clear you call this for per-post traffic breakdowns, and the 'post nobody has read yet returns empty lists' note heads off a false-empty interpretation. However, there is no explicit guidance about when to prefer get_post_stats, get_post_engagement, or list_traffic_sources instead.

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 safe-read profile (readOnly, idempotent, non-destructive), so the description correctly spends its budget on output semantics instead: churn excludes free unsubscribes, new-subscriber math includes cancellations, and revenue is annualized rather than cash received. These are exactly the misreadings an agent would otherwise make. It stops short of noting snapshot staleness, rate limits, or auth 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?

Front-loaded with the returned metrics, then the measurement point, then per-field caveats; every sentence carries information. It is dense to the point of being run-on, and the field caveats would scan better as separated clauses, but nothing is filler.

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

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

With no output schema, the description carries the full burden of explaining returns, and it does so by naming the specific fields (subscribers_churned, subscribers_new, revenue_usd) and their non-obvious definitions. For a single optional enum parameter and a read-only snapshot tool, nothing material is left for the agent to guess.

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

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

Schema coverage is 100% and the enum plus 'Default: 30d' are already in the schema, so the baseline would be 3. The description earns a point by explaining what the period actually anchors — totals are measured at the end of that window — which the schema alone does not convey.

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

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

Opens with a concrete enumeration of the resource returned (total and paid subscribers, new subscribers, paid cancellations, estimated revenue) plus the measurement window, so the agent knows exactly what this tool produces. It is distinguishable from get_daily_stats by the 'totals at the end of the period' framing, though it never names that sibling explicitly.

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

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

Usage is only implied: the '7, 30 or 90 days' period framing signals this is a coarse-grained aggregate tool versus daily stats. There is no explicit statement of when to choose this over get_daily_stats, get_audience_insights or get_post_stats.

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

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

Annotations already cover readOnly, idempotent, non-destructive behavior. The description adds useful beyond-annotation context: reading the counts marks nothing as read, which prevents an agent from assuming a side effect. It does not discuss rate limits or refresh behavior, but for a simple read tool with annotations this is adequate.

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

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

The description is front-loaded and compact. It repeats the three badge categories in the first and second sentences, which is slightly redundant, but the second sentence earns its place by expanding activity into likes, replies, new followers, and restacks.

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

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

With no output schema and no parameters, the description carries the burden of explaining what is returned. It does so by enumerating the three badge types and clarifying that reading is non-mutating, leaving no material gap for calling 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?

There are zero parameters, so the baseline is 4. The description does not need to explain parameter syntax, and the empty schema is consistent with the tool's purpose.

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 retrieval: unread direct messages, message requests, and activity notification counts. It names the exact resource categories and frames the tool as returning the Substack app badges, so an agent can tell this apart from list_activity or list_conversations 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?

Usage is implied by the badge/notification framing, but the description does not explicitly say when to use this tool versus alternatives such as list_activity or get_daily_stats. It also gives no prerequisites or exclusions, leaving the agent to infer context.

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

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

Adds real context beyond annotations: the action is performed under the caller's identity ('as you'), and the author is notified via their activity feed — a side effect not captured by openWorldHint. This helps explain the non-readOnly/non-idempotent flags, though it doesn't spell out reversibility or that the like is publicly visible.

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

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

Three sentences, front-loaded with the action and the toggle, followed by the ID-space caveat and the side effect. No filler, though the 'Adds your heart...' clause partly restates the opening verb.

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 toggle tool with no output schema and full schema coverage, the description supplies the essentials: identity under which the like occurs, cross-entity ID sharing, and the visible side effect. Only explicit guidance on when to prefer like_post over 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 baseline is 3; the description adds value by clarifying that comments and Notes share one ID space and naming list_notes and search_substack as valid ID sources, which the schema's comment_id text only partly covers.

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 (like/unlike) and precise resources (a comment, a Note, or a Note reply) with actor scope ('as you'). It is clearly separable from sibling like_post, which the phrasing implicitly leaves for posts rather than comments/Notes.

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

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

Explains the toggle mechanism ('or removes it with unlike'), so an agent knows this one tool handles both directions rather than needing a separate unlike tool. It also gives context for where valid IDs come from. It stops short of explicitly contrasting with like_post or stating when not to use it.

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

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

The description says "Liking twice keeps one like," which indicates idempotent behavior for repeated likes, but the annotations declare idempotentHint=false. This is a direct contradiction. Other behavioral context, such as the author seeing the like, is useful, but the idempotency mismatch is serious.

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

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

The description is front-loaded and appropriately short. The phrase "as the heart under a post does" is somewhat redundant and could be trimmed, but overall it is efficient.

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

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

For a simple two-parameter tool with full schema coverage and annotations, the description covers the core action and visibility. However, the idempotency contradiction means the behavioral picture is not fully reliable.

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 post_id and unlike are already documented in the schema. The description reinforces the unlike behavior but adds no additional parameter syntax or constraints beyond what the schema provides.

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

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

The description states a specific verb and resource: like or unlike a Substack post as the authenticated user. It clearly distinguishes posts from sibling tools like like_comment by naming the resource directly.

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

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

It explains how to remove a like via the unlike option and clarifies that the action is performed as the current user. It does not explicitly compare against like_comment or discuss when not to use this tool, but the usage context is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real value by saying "Reading the list marks nothing read" and by naming next_cursor for paging, but does not cover rate limits, ordering guarantees beyond "newest first", or empty-state 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?

Dense but front-loaded: the first sentence states what the feed is and its ordering, then successive clauses cover types, grouping, per-item fields and pagination. Nearly every clause carries information an agent needs and nothing is redundant.

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

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

With no output schema, the description compensates well by describing returned fields (type, from, people, comment_id/text, on_comment_id, on_post_id) and the pagination token. What remains thin is the selection guidance against siblings, but the call itself is fully specified.

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 both cursor and the filter enum (all/replies/restacks) are fully documented in structured fields. The description spends its parameter-adjacent text on the item `type` values (note_reply, follow, mention…) and on from/people fields, which are response fields rather than inputs, so it adds little direct meaning to the two actual 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?

Opens with a concrete verb and resource: the Substack notifications feed (replies, likes, followers, restacks), ordered newest first. It is clearly distinct from list_comments, get_unread_counts and list_notes by content, though it never names a sibling to contrast 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?

It implies context ("Returns the Activity tab of the Substack app") and explains paging via next_cursor, but gives no explicit when-to-use versus when-not, and does not say how this differs from get_unread_counts or list_comments when an agent wants reply/mention data.

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 the description adds genuinely new behavior: results come back all at once (no pagination), oldest first, replies nested under parents, deleted comments omitted, and the exact truth condition for 'replied'. That is real disclosure the annotations cannot carry.

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

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

Four tight sentences, front-loaded with the resource and its returned shape before the parameter nuance. The closing 'Pass comment_id to reply_to_comment' is slightly under-specified about where comment_id comes from, but overall there is little waste.

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

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

No output schema exists, and the description compensates by describing the returned fields, ordering, nesting, and exclusion rules. With only two fully documented parameters, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by clarifying that 'replied' reflects a reply anywhere in the thread while unanswered_only narrows to top-level comments only — a distinction the schema text ('Skip threads you already replied to') leaves ambiguous.

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

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

Opens with a specific verb and resource ('Comments on a post') and enumerates the returned fields (author, text, replied). It does not name a sibling it is not (e.g. list_note_replies, get_conversation), so an agent must infer the boundary from the resource name 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?

'unanswered_only keeps only top-level comments where you did not' reply gives a concrete condition for selecting the optional parameter, and 'Pass comment_id to reply_to_comment' routes the agent to the follow-up tool. There is no explicit statement of when not to use this tool versus sibling listing tools.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description still adds genuinely non-obvious behavior — 'Reading the list does not mark anything read' — which an agent could easily assume otherwise. It also enumerates the returned fields (who, last message, its time, unread count, message-request flag), compensating for the absent output schema.

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

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

Every sentence carries distinct information: scope first, then return contents, then the exclusion, then the side-effect clarification, then the routing hint. No repetition of the title or annotations, and nothing padded.

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

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

With no output schema and only two well-documented parameters, the description supplies exactly the missing pieces: what the rows contain, ordering, exclusions, and the read-state side effect. An agent can call this correctly and hand off to get_conversation using the returned conversation_id.

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

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

Schema description coverage is 100%, so both parameters (cursor, unread_only) are fully documented in the schema. The description adds nothing about either parameter — no note on pagination flow or when to set unread_only — so the baseline 3 applies.

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

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

The description states a specific verb and resource ('List your direct-message conversations, latest first, with the last message') and immediately bounds the scope by excluding publication chats. It is clearly distinguishable from siblings like get_conversation and get_unread_counts without opening a schema.

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

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

It states what is included (one-to-one and group DMs), what is excluded (publication chats), and routes the agent forward: 'Pass conversation_id to get_conversation or send_message.' That is explicit when-to-use plus named alternatives with the condition that selects them.

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

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

Annotations already establish that this is read-only, idempotent, non-destructive, and closed-world. The description adds useful behavior beyond that: Substack ordering, pagination via next_cursor, and data limitations where author.handle is empty and url is null.

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

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

The description is front-loaded with scope, then covers returned fields, nested-reply usage, data caveats, and pagination. The sentences are short and every one adds useful information without obvious 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?

For a two-parameter read-only tool with no output schema, the description covers returned fields, ordering, direct-reply scope, nested traversal, author/url quirks, and pagination. That is enough for an agent 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 baseline is 3, but the description adds meaning for note_id by explaining how to list nested replies using a reply's note_id. The cursor guidance mostly restates the schema's next_cursor description.

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

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

The description clearly states that it returns direct replies under one Note, including author, text, and likes, in Substack's order. It is scoped enough to distinguish from list_notes, but it does not explicitly contrast against sibling tools such as list_notes or reply_to_note.

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

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

It explains that the tool returns direct replies under one Note (yours or anyone's), notes that nested replies are listed by passing their note_id, and says to page with next_cursor. It lacks explicit when-not-to-use or alternative-tool guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real substance: newest-first ordering, the concrete fields returned (text, time, likes, restacks, reply count, link), and the omission of posts and restacks. It says nothing about auth requirements or any per-page limit for next_cursor pagination.

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 scope exclusions, then pagination, then sibling routing – a logical order with no filler. Minor redundancy: 'newest first' appears in both the first and second sentences.

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

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

There is no output schema, and the description compensates by enumerating the returned fields and their ordering. Pagination, the default-user case, and the excluded content types are all covered, leaving nothing an agent needs in order 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%, with both parameters documented ('Default: you' and 'next_cursor from the previous page'). The description's 'Without user it lists yours' and 'Page with next_cursor' essentially restate that, adding no syntax or handle-format detail beyond the schema's example. 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 ('Notes posted by you or any other Substack user') plus ordering and included fields, and explicitly excludes 'Posts and restacks of posts', which is the main ambiguity an agent would have against list_posts or get_feed. It also names the sibling that consumes its output (list_note_replies), so the tool is separable 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?

'Without user it lists yours' sets the default case, and 'Pass note_id to list_note_replies, like_comment or reply_to_note' routes the agent downstream. The exclusion of posts/restacks bounds scope. It lacks an explicit statement of when to prefer a different listing tool (e.g. get_feed, list_activity), so it stops short of full alternative guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond that: ordering is newest first, scheduled posts include publish time, and pages are capped at 50 with cursor passthrough for pagination.

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 reasonably short and front-loads the core purpose, but the first two sentences redundantly repeat 'Posts of your publication, newest first.' That duplication wastes space without 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?

For a read-only list tool with full schema coverage and annotations covering safety, the description is nearly complete: it covers ordering, returned fields (status and audience), scheduled publish time, and pagination behavior. Full return shape is not described, but no output schema exists to compensate for that.

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 limit, cursor, and status. The description reinforces pagination and status filtering, but it introduces a naming mismatch by saying 'pass next_cursor back as cursor' when the parameter is simply named cursor, which slightly weakens clarity.

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 ('lists posts of your publication') and adds useful scope details ('newest first, with status and audience'). It does not explicitly differentiate from siblings like get_post or list_notes, but the listing purpose is unambiguous.

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

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

Usage is implied through 'Filter by status to see drafts or scheduled posts' and the pagination note, but there is no explicit guidance on when to use this versus alternatives such as get_post for a single post. Adequate but with clear gaps.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the description's job is to add substance beyond safety. It does: it discloses the returned fields (ID, name, slug), that readers see tagged posts at /t/{slug}, and that hidden tags represent posts without a public page — meaningful domain behavior. It does not mention ordering or pagination, which would push it higher.

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

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

Three tight sentences, front-loaded with the definition, followed by return shape and the hidden-tag caveat, ending with the handoff to tag_post. 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?

No output schema exists, so the description must carry the return-value burden — and it does, naming the three fields and the hidden-tag semantic. Combined with annotations covering safety, 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?

With zero input parameters the baseline is 4; there is nothing to mis-describe. The description uses the space instead to describe the output shape (ID, name, slug) and how tag_id feeds tag_post, which is useful even though not strictly a parameter.

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

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

States a specific verb and resource ('Returns every post tag of your publication') and immediately disambiguates from sibling tools like list_subscriber_tags and create_post_tag by naming the resource type and scope. An agent can tell what this does without opening the schema.

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

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

The final sentence 'Pass tag_id to tag_post' explicitly routes the agent to the downstream tool that consumes this output, which is a clear usage signal. It lacks an explicit 'when not to use' or mention of alternative tag-listing tools, keeping it 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 readOnly/idempotent/non-destructive, but the description adds genuine context: the table is rebuilt in the background, so recent recommendations may be missing while counts already include them. That staleness caveat is exactly the kind of disclosure annotations can't convey. Return shape is also sketched.

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 and the Audience > Recommendations target, then the staleness caveat and the publication_id mode. Dense but each sentence carries information; the background-rebuild note is a little buried but appropriate.

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

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

For a read-only, no-required-param tool with no output schema, the description covers purpose, both parameter modes, return framing, and the eventual-consistency caveat. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning: 'received' also indicates whether the recommendation is mutual, and publication_id only applies to given direction. This enriches the enum semantics beyond the schema.

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

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

States a specific verb+resource ('Publications you recommend, or that recommend you') and scopes it to 'with the subscribers each sent'. An agent can distinguish this from the mutating sibling recommend_publication immediately.

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 what 'given' vs 'received' yield and states the default (given). Also clarifies the alternate mode: 'publication_id checks one recommendation of yours directly.' It doesn't explicitly name the sibling recommend_publication as the write alternative, keeping it 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 cover the read-only, idempotent, non-destructive profile, and the description adds real value beyond them: it explains that live is false during setup, what subscribed_by_default means, and that a publication without sections returns an empty list. It does not discuss auth/permission requirements, which is the only notable gap.

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

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

Four short sentences, front-loaded with the resource definition followed by return fields, two field-level clarifications, and an edge case. Every sentence earns its place with no repetition of schema or annotations.

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 zero parameters, full annotation coverage, and no output schema, the description carries the return-value burden itself and does so by naming the returned fields and explaining the two non-obvious ones. 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?

The tool takes no parameters, so the baseline is 4 and there is nothing for the description to compensate for. The description correctly focuses on return-field meaning instead.

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

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

The description defines the resource precisely (sections are the separate newsletters inside a publication) and states what is returned, so an agent can tell this apart from list_posts or list_subscribers. It stops short of naming an alternative sibling explicitly, which keeps it from a 5.

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

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

There is no explicit 'use this when...' guidance or exclusion of alternatives; usage is only implied by the name and the return description. For a zero-param listing tool this is adequate but leaves the agent to infer context.

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

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

Goes well beyond the readOnly/idempotent annotations: discloses 500-row page size, the subtle pagination-plus-filter interaction, background table population causing recently-added subscribers to be missing, and that paid includes founding members. These are exactly the behaviors an agent would otherwise get wrong.

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

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

Front-loads the resource and return fields, then behavior and caveats; nearly every sentence carries information. The opening 'Subscribers with plan, start date and activity rating.' is a fragment that reads as a field list and slightly hurts flow, but nothing is padding.

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

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

With no output schema, the description correctly compensates by listing the returned fields, and it covers pagination mechanics, filter semantics, and eventual-consistency lag. An agent has everything needed to call this correctly and interpret short or empty pages.

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, and the description earns above that by clarifying semantics the schema doesn't: cursor is the previous page's next_cursor, and plan/since scope inside a page rather than across the result set. The enum detail ('paid includes founding members') also adds 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?

Names a specific verb and resource ('Lists subscribers, newest first, from the subscriber dashboard') and enumerates the returned fields (plan, start date, activity rating). It is clear about scope, but never explicitly contrasts itself with siblings like export_subscribers, add_subscriber, or list_subscriptions, so an agent must infer the boundary.

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

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

Gives concrete operating instructions: pass next_cursor back as cursor, filters apply within each page so filtered pages can be short or empty. It does not name an alternative tool or state when-not-to-use (e.g. bulk export), which keeps it below 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?

The annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing visibility semantics ('Subscribers never see tags') and anchoring the result set to a known UI location (Audience > Subscribers > Tags).

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, each doing work: what the resource is, what is returned, who can see it, and what to do with the result. The identity of the resource is front-loaded before the return details, 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 no params, no output schema and full annotation coverage, this is about as complete as the description needs to be: it names the resource, describes the returned fields (IDs), gives UI parity for verification, and points to the follow-up tool. Nothing required to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4; the schema carries nothing that needs explaining. The only parameter-like mention, 'Pass tag_id to tag_subscribers', refers to a sibling tool rather than an input here, but it is clearly framed as a downstream action and does not create confusion.

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

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

The description gives a specific verb and resource — it returns the publication's subscriber tags with their IDs — and the phrase 'Tags you use to group subscribers' distinguishes it from the sibling list_post_tags, which covers posts rather than people. The distinction is inferable rather than stated outright, keeping it below a 5.

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

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

Usage is implied rather than spelled out: the tool is clearly the discovery step before tag_subscribers, and 'Pass tag_id to tag_subscribers' hints at that workflow. However, it never says when to prefer this over list_post_tags or that it should be called first when tag IDs are unknown.

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. The description adds value beyond them by promising a complete unfiltered result set ('returns every publication'), defining the field list, and disclosing the exclusion of own publications, so an agent knows the result is exhaustive with no pagination or filtering concerns.

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 return fields. The second sentence partly restates the first ('every publication your account subscribes to'), a small redundancy, but the plan-type enumeration (free, paid, comp, founding, gift) and the exclusion note earn their space.

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

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

With no parameters and no output schema, the description must carry the return-value burden, and it does: it names the four returned attributes and enumerates the possible plan values. Nothing an agent needs in order to call this correctly is missing.

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

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

The tool takes zero parameters, so there is no per-parameter semantics to explain; the baseline for a 0-param schema is 4. Nothing in the description misdescribes the parameter surface.

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 resource (publications the account subscribes to) and enumerates the returned fields: name, link, plan, and email-delivery status. It also explicitly contrasts with a related concept by noting that your own publications are excluded, so an agent can distinguish it from list_subscribers.

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

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

It sets clear scope: 'every publication your account subscribes to, as Settings > Subscriptions lists them' and states the exclusion of your own publications, which functions as a when-not rule. It stops short of naming a sibling alternative (e.g., list_subscribers for the inverse direction), so routing between sibling tools is only implied.

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

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

Annotations already cover read-only and idempotency, so the description's job is to add behavior, and it does: sort order ('most views first'), pagination mechanics via next_cursor, and the exact fields per row (category, views, unique visitors, free/paid subscribers). Missing only things like rate limits or whether the period is relative to now.

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

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

Two dense sentences, front-loaded with the purpose before the return-shape detail. Every clause carries information: scope, sort order, field list, and pagination.

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

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

With no output schema, the description carries the return-shape burden and does so fully by enumerating the row fields and the ordering. Combined with 100% schema coverage for the three optional params, an agent has everything needed to call and page through it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics beyond the schema: it explains the sort key that makes limit/cursor meaningful and clarifies that the cursor pages through a views-ordered list. It does not restate the enum values or the limit cap, which the schema already handles.

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

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

States a specific verb and resource ('Where your publication's visitors came from in a period') and scopes it to publication-level traffic sources, which separates it from get_post_traffic and get_audience_insights. The mapped Analytics location ('Analytics > Traffic > Traffic sources') further pins down exactly what is returned.

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 'in a period' phrasing and the publication-level framing imply when this is the right call, but no alternative tool is named and no exclusion is given (e.g. use get_post_traffic for a single post). An agent must infer the boundary from the sibling names alone.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered; the description usefully adds that only one comment sits above all others and that ownership of the post is required. It does not state outright that pinning a second comment displaces the existing pin, nor what the response looks like, leaving some mutation behavior to inference.

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

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

The core action is front-loaded, but the second sentence largely restates the first ('Pins one comment ... or unpins it' after 'Pin a comment ... or unpin it'). Two of the three sentences cover the same ground, which is wasted space even though the total length is short.

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 only two parameters, full schema coverage, annotations, and no output schema, the description covers ownership scoping, the one-pin-per-post rule, and the error case adequately. The remaining gap is whether an existing pin is replaced or preserved, which an agent would want to know before calling a destructive operation.

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

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

Schema coverage is 100% and the `unpin` boolean already documents its own default, so the schema does the heavy lifting. The description gestures at the unpin mode in prose but adds no format, ordering, or edge-case detail beyond what the schema 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?

The description names a specific verb+resource ('Pin a comment') and pins down scope: 'one comment on a post of your publication above all others,' plus the asymmetry that comments on other people's posts error out. That is enough to separate it from like_comment, reply_to_comment, or delete_comment, though it never names a sibling for routing.

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?

'or unpin it' and 'a comment on someone else's post returns an error' give clear use context and one concrete failure condition. It lacks explicit when-not guidance or a pointer to which tool to use instead for the adjacent operations, so it stops short of 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?

Beyond annotations, the description discloses that publishing waits for owner approval and that each call is confirmed by default unless switched off. It also describes the scheduled outcome, including the scheduled status and published_at value. This adds useful operational context, though it does not fully discuss public visibility or irreversibility beyond the destructive annotation.

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

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

The description is front-loaded with the core action and is reasonably compact. A few clauses repeat schema-level details, such as text length and the published-post constraint, but overall it remains efficient.

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

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

Given the 100% schema coverage and rich annotations, the description covers the main behavioral questions: scheduling, approval, link cards, and text limits. It is nearly complete, with only minor gaps around approval failure or return behavior for immediate posts.

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 mostly repeats schema details about body length and link_post_id, though it adds some useful outcome context for publish_at by explaining the scheduled status and published_at behavior.

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

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

The description states a specific verb and resource: publishing a short post in Substack Notes, with optional scheduling and a link card. It is clear what the tool does, but it does not explicitly differentiate itself from sibling tools such as publish_post or schedule_post.

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

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

It explains the key internal usage distinction: omit publish_at to post now, include it to schedule. However, it gives no guidance on when to use this tool versus alternatives such as schedule_post, publish_post, or create_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 flag destructiveHint, openWorld and non-idempotent, and the description adds substantial context on top: the email cannot be recalled, pre-publish validation can abort the call, section routing fallback order, and that owner approval gates execution. That is real behavioral disclosure 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?

Front-loaded with the core action and dense with useful detail, but the opening 'Publish a draft now. Publishes a draft immediately' is mildly redundant. Overall efficient for the amount of behavioral information conveyed.

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

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

For a destructive, approval-gated publish tool with no output schema, the description covers failure modes, irreversibility, routing, and confirmation behavior. Nothing material an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the section_id resolution chain (explicit section_id, then the draft's section, then the main publication) and clarifies send_email's dual-channel effect, going beyond the schema's terse notes.

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

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

States a specific verb and resource ('Publish a draft now') and implicitly contrasts with schedule_post, create_draft, and unpublish_post. An agent can tell exactly what this does without opening the schema.

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

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

The word 'now' plus 'immediately' clearly positions it against scheduling, and the pre-publish check and approval-wait conditions tell the agent when the call will fail or block. It stops short of naming the sibling alternatives explicitly, so not 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?

Adds substantial behavior beyond the annotations: the recommendation is surfaced to people who subscribe to you, notifies the author, and waits for the owner's approval. The confirm-by-default and per-tool opt-out detail is exactly the kind of operational context destructiveHint/idempotentHint cannot convey, and nothing here contradicts 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?

Front-loaded with purpose and then layered side effects, approval, and parameter meaning in a compact block with no filler. Slightly dense/run-on in places, but each 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?

For a write tool with annotations and no output schema, the description covers the important unknowns: public visibility, author notification, approval gating, and confirmation behavior. Only the outcome when the owner declines to approve is left implicit.

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

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

Schema coverage is 100%, so all three parameters are already documented. The description restates blurb as 'the short reason readers see' and remove as 'takes the recommendation back', which overlaps closely with the schema text rather than adding new constraints or formats; 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 opening sentence gives a specific verb and resource ('Recommend another publication to your readers') and explicitly covers the inverse operation via 'or stop recommending it'. It also ties the action to a concrete product surface (Growth > Recommendations), so an agent can distinguish it from list_recommendations 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?

Clear about the conditions of use: add by default, remove with the `remove` flag, and confirmation is on by default but switchable for this tool. It stops short of explicitly routing the agent elsewhere (e.g. 'use list_recommendations to view existing ones'), so it is strong context without named alternatives.

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

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

Beyond the destructive/readOnly annotations, the description explains the visible effect: the text disappears, readers see a moderator-removal notice, and replies remain. It also discloses error behavior, default confirmation, and owner approval, which are important operational details.

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

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

The description is front-loaded with the core action and then adds only decision-relevant details. Every sentence contributes to correct tool selection or invocation.

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

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

For a destructive one-parameter mutation tool with no output schema, the description covers the important behavior: effect on readers, retained replies, sibling distinction, error case, confirmation, and approval. Nothing critical for an agent to call it correctly appears to be missing.

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

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

Schema description coverage is 100%, and the single comment_id parameter is already documented as coming from list_comments. The description adds useful context about whose comment can be removed, but it does not add parameter-level syntax or format details 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, scopes it to comments on your publication, and directly distinguishes it from the sibling delete_comment. An agent can tell exactly what operation this performs without opening the schema.

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

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

It explicitly says to use delete_comment for your own comments and explains that commenting on someone else's post returns an error. The moderator-only context and confirmation behavior further clarify when this tool applies.

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

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

Beyond the destructiveHint annotation, the description discloses key consequences: the subscriber gets no notice, paid subscriptions are cancelled with a partial refund, unknown emails cause an error, and calls are confirmed by default unless switched off. It also notes that the tool waits for owner approval, which is important operational context.

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

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

The description is front-loaded with the core action and then adds relevant consequences. It is slightly repetitive in the opening two sentences, but every later sentence contributes useful behavioral detail.

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

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

For a destructive, single-parameter mutation with no output schema, the description covers the essential side effects, error condition, confirmation behavior, and approval requirement. An agent has enough context to invoke it correctly and understand the consequences.

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 single email parameter is already fully documented by the schema. The description reinforces that the email must already be on the list and that a missing email errors, but it does not add syntax or format meaning 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 precise verb and resource: 'Remove one email from your subscriber list.' It also distinguishes the action from sibling add_subscriber by clarifying the effect and timing of adding versus removing.

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

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

It gives clear context for use: removing a subscriber removes them from the list, sends no notice, cancels paid subscriptions, and returns an error if the email is not present. It does not explicitly name alternatives such as list_subscribers for verification, but the relevant sibling add_subscriber is referenced.

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

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

Beyond the annotations, the description discloses important behavioral details: the reply is public to everyone who can read the post, the author receives Substack's usual notification, external comments fail, and the call involves confirmation/owner approval. These are meaningful side effects for a write operation.

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

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

The definition is appropriately sized and front-loads the core action. There is some slight redundancy between the first two sentences, but the extra context about visibility, notifications, and approval is relevant 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?

For a two-parameter write tool with complete schema coverage and no output schema, the description covers the key side effects, visibility, error condition, notification behavior, and approval requirement. An agent has enough information to invoke it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented in the input schema. The description does not add syntax or format details beyond the schema baseline, which is acceptable when the schema carries the parameter burden.

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—replying under a comment on the user's own post—and clarifies the scope by noting that a comment elsewhere returns an error. This distinguishes it from sibling tools like reply_to_note and like_comment.

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 clearly establishes the usable context: the comment must be on a post of the user's publication, and comments elsewhere on Substack produce an error. It does not explicitly route the agent to sibling alternatives, but the constraint is strong enough for correct selection.

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

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

Beyond the annotations, the description discloses public visibility, the notification sent to the author, Markdown support, the 1,000-character cap, default per-call confirmation, and owner approval. These are significant behavioral details for a public write operation.

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

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

The purpose is front-loaded and most sentences carry useful information. There is minor redundancy between the opening sentence and the following explanation, and the confirmation/approval wording could be tighter.

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 annotations and fully described two-parameter schema, the description is complete enough to call the tool correctly. It covers visibility, formatting, limits, notification, confirmation, and approval without needing an output schema.

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

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

Schema coverage is 100%, so both parameters are already documented. The description adds useful body semantics by specifying a 1-character minimum and supported Markdown formatting, though it does not add much beyond the schema for note_id.

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

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

The description gives a specific verb and resource: replying under a Note or Note reply. It also scopes the action to any Note, yours or anyone's, which distinguishes it from posting a new Note or replying to a comment.

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 clearly establishes the context for use: posting a reply under a Note or under an existing Note reply. It does not explicitly name alternatives such as reply_to_comment, but the Note-specific scope gives enough context to select it correctly.

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

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

Beyond the annotations (destructive, non-idempotent, open-world), the description discloses the confirmation/owner-approval flow, that the schedule can be toggled on this tool, that a scheduled post remains editable until it goes out, and that email delivery is a side effect controllable via send_email. These are exactly the facts an agent needs before committing a destructive, hard-to-undo action.

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

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

The first two sentences say nearly the same thing twice ("Publish a draft at a set time, on the web and by email" / "Schedules a draft to go live at the time you set, on the web and, unless send_email is false, by email"), and the confirmation sentence trails after the substantive constraints. Constraints are covered but the front-loading is undermined by that duplication.

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

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

For a mutation tool with annotations but no output schema, the description covers validation failures, approval behavior, post-scheduling editability, target-section routing, and email side effects — enough to call it correctly. Missing only what the call returns and how to verify the scheduled result.

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

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

Schema coverage is 100%, so all four parameters are already documented, including section_id's fallback chain and send_email's default. The description restates the section resolution order and the email opt-out but adds no new syntax or format detail; 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?

The description opens with a specific verb and resource ("Publish a draft at a set time, on the web and by email") and the phrase "at the time you set" distinguishes it from immediate publishing (publish_post) and from cancel_scheduled_post. An agent can identify the operation without inspecting 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 states concrete preconditions — the time must carry a time zone and be in the future, and Substack's pre-publish check blocks missing titles or empty bodies — which tells the agent when the call will fail. It does not explicitly compare against the close alternatives publish_post or update_draft, so the routing guidance is implied rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description adds context beyond them: results are bucketed into people/posts/Notes and later pages may contain only posts and Notes. That pagination-shape caveat is genuinely useful behavioral detail.

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

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

Three sentences, front-loaded with the action and result shape, then follow-on tool IDs, then the paging caveat. Every sentence carries information.

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

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

With no output schema, the description responsibly describes the return grouping and pagination behavior. It could note result ordering or empty-result behavior, but an agent has enough to invoke and consume it correctly.

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