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

No annotations are provided, so the description carries the full burden. It transparently discloses caching behavior, the use of an API instead of a browser, and the requirement for an authenticated session. This covers key behavioral aspects, though it does not mention error handling or response details beyond the 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?

The description is four concise sentences, front-loaded with the primary purpose, and each sentence adds relevant detail without redundancy. It avoids jargon and is well-structured for quick consumption by an AI agent.

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

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

For a tool with only two parameters and an output schema, the description covers essential context: caching, API access, authentication, and the cleaning/formating. It is complete enough for most use cases, though it omits potential edge cases like failure modes or idempotency guarantees, which are not critical here.

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

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

Schema coverage is 0%, requiring the description to compensate. It explains force_refetch's effect on caching but does not clarify what url_or_id actually accepts beyond the schema's generic string type. This partial compensation leaves a gap for the primary 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 clearly states the verb 'Fetch' and the resource 'a saved note's full content', with additional value of 'cleaned and formatted for LLM consumption'. This distinguishes it from sibling tools like get_post_content or get_saved_note by explicitly focusing on notes and formatting for LLMs.

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?

While it mentions the caching mechanism and the API-based fetch, it does not explicitly contrast with alternatives or state when to prefer this over get_saved_note or get_post_content. It implies usage for fetching note content but lacks explicit when-not-to-use guidance or alternative recommendations.

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

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

With no annotations provided, the description fully carries the transparency burden. It discloses caching behavior, the fetch source (window._preloads blob), text conversion process, auth requirements, and failure mode with a suggested remediation. This is exceptional behavioral disclosure for a read tool, covering side effects and edge cases.

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

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

The description is compact yet detailed, with three sentences covering purpose, behavior, and failure handling. The second sentence is long and clause-heavy, but every piece of information earns its place given the tool's complexity. It is front-loaded with the core purpose and avoids unnecessary 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?

Given the tool's complexity, no annotations, and an output schema present, the description is remarkably complete. It covers caching, extraction method, auth prerequisites, and failure handling with a user- actionable next step. Nothing critical is omitted for an agent to invoke this tool safely and effectively.

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 zero descriptions, but the tool description explicitly explains force_refetch semantics (overrides cached content) and implies url_or_id identifies the saved post. While the exact format for url_or_id isn't specified, the parameter name and context are sufficiently self-explanatory for an agent. The description compensates well for the schema's lack of 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 clearly states the tool fetches a saved post's full content, cleaned and formatted for LLM consumption. This specific verb+resource combination distinguishes it from siblings like list_saved_posts or get_saved_post, which likely handle metadata or listings.

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 establishes clear context: use when you need the full content of a saved post, with prerequisites (authenticated session) and caching behavior. It does not explicitly name alternative tools for different use cases, but the purpose is unambiguous and the troubleshooting tip for failed fetches adds practical 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?

The description clearly identifies that this is a read operation returning cached data, but with no annotations present, more context is needed—such as staleness implications, error handling, or authentication requirements. It is not misleading but stays surface-level.

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

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

A single, front-loaded sentence that communicates action, resource, and details without redundancy. Every clause adds value and no space 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?

For a simple read tool with an output schema, the description sufficiently covers purpose and parameter semantics. It does not address edge cases like missing or invalid IDs, but overall it gives an adequate mental model for an agent to select and use the 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 parameter `url_or_id` is given meaningful explanation: it can be a URL or a local identifier. Since the schema description coverage is 0%, this is essential additional context. A concrete example or format hint would have been useful but is not required for the one-parameter tool.

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 ('Retrieve'), specific resource ('full cached note details'), and enumerates returned fields ('author, body, engagement counts'). This clarifies the tool's scope and distinguishes it from sibling tools like get_note_content or search_saved_notes.

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

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

The description provides no guidance about when to choose this tool over alternatives such as get_note_content or sync_saved_notes. It specifies the lookup mechanism (by URL or local ID) but does not explain contexts, exclusions, or constraints.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose one genuinely valuable trait: content_text is empty until get_post_content has fetched the post, revealing a cache-state dependency. It says nothing about authentication, whether the call hits the network or only a local cache, or what happens when the URL/ID is not saved — significant gaps for a tool with zero annotation coverage.

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

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

Two sentences: the first front-loads the capability and its accepted inputs, the second carries the one caveat an agent needs. No filler, no repetition of the tool name, and nothing that could be trimmed 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?

A return value schema exists, so the description need not re-explain output structure — yet it still names the key fields, which helps. Input documentation is thin in the schema and partially rescued here, but with no annotations the definition should say more about failure modes (unsaved post) and whether lookup is cache-only.

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

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

Schema coverage is 0% — url_or_id is documented only as a bare string. The description compensates by telling the agent the three accepted identifier forms (URL, local ID, Substack post ID), which is real added meaning beyond the schema. It still does not clarify which form to prefer or how ambiguous inputs are resolved.

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 (Retrieve) and resource (full cached post details) and enumerates what comes back: timestamps published_at/saved_at and content. The reference to get_post_content hints at the boundary with that sibling, but it never frames the distinction as 'use this instead of X', so differentiation is implied rather than stated.

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

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

There is no explicit when-to-use or when-not-to-use clause, and no comparison against siblings like get_post_content, get_saved_note, or list_saved_posts. The final sentence implies a precondition (content is only populated after a prior get_post_content call), which is useful but leaves the agent to infer the rest.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It explains that values are discovered from local cache and are dynamic, but it does not explicitly state safety traits (e.g., read-only, no side effects) or mention whether the cache might be stale or require syncing beforehand.

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 concise, with the core function stated first and the rationale in the second sentence. Every sentence provides value and there is no redundancy or 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?

Given the simplicity (0 params) and presence of an output schema, the description is mostly complete. It covers what the tool does, where it reads from, and why it uses live values. It could mention prerequisites like cache syncing, but that is a minor gap.

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

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

The tool has zero parameters and the schema coverage is 100%, so the baseline is 4. The description adds context about why there are no parameters (it scans actual values in use) which is helpful, though not strictly necessary.

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 it lists distinct audience tiers from local cache with post counts. It differentiates itself from sibling tools by focusing on audience tiers specifically, and the context about discovering actual values rather than hardcoded enums adds clarity.

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 implies usage for discovering dynamic audience values rather than relying on a static enum, but it does not explicitly state when to use this tool versus alternatives or mention any exclusions. No sibling tool is referenced for comparison.

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 are absent, so the description must disclose behavioral traits. The description only mentions listing local cache with post counts, but does not state whether the operation is read-only, requires prerequisites, or has side effects. It also does not clarify what 'local cache' means operationally.

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 a single, well-structured sentence that front-loads the core purpose and includes relevant detail ('with post counts'). No redundancy or unnecessary 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?

Though the tool is simple with no parameters and an output schema, the description lacks critical contextual details such as whether it is a read-only operation, how 'local cache' is populated, and when to choose this over sibling tools. Given the importance of an agent knowing side effects and usage, the description is minimally viable but has clear gaps.

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

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

The tool has zero parameters, so the input schema is inherently fully covered. The description correctly omits parameter details, warranting the baseline score of 4 for no-parameter tools.

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

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

The description clearly states the tool lists all publications in local cache and includes post counts, specifying the exact resource and scope. It is distinct from sibling tools like list_saved_posts, which focuses on saved posts rather than 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?

No guidance is provided regarding when to use this tool instead of alternatives like search_saved_posts or sync_saved_posts. There are no explicit context cues, prerequisites, or exclusions.

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

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

With no annotations, the description carries the full burden, and it does disclose a genuinely non-obvious quirk: the default sort_by ('saved_at') yields no meaningful ordering for notes, and 'cached' signals results may be stale relative to the server. It omits any statement on auth requirements, cache staleness/sync behavior, or rate limits.

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

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

Three short sentences, front-loaded with purpose before parameter nuance, with no filler. The saved_at parenthetical is slightly convoluted and could be tightened, 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?

An output schema exists, so return values need not be explained, and the description covers purpose, filters, and sorting. It still leaves gaps on the cached/sync relationship, how it differs from search_saved_notes, and pagination defaults for a 5-parameter tool.

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

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

Schema description coverage is 0% across 5 parameters, so the description must compensate and only partially does. It explains sort_by's two values and what restacks_only does, but limit, offset, and author are covered at best vaguely by 'pagination and optional author/restack filters' with no accepted format or author identifier semantics.

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

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

States a specific verb (List) and resource (cached saved notes) plus the supported filters, which separates it from the sibling search_saved_notes. It stops short of naming that sibling explicitly, so an agent still has to infer list-vs-search, but the core 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 only implied: 'cached' hints that sync_saved_notes may be needed first and the list/search split is left to inference. The note that sort_by='saved_at' produces no meaningful order is a useful selection hint (prefer 'posted_at'), but no explicit when/when-not or alternative tool is named.

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

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

With no annotations, the description carries the full behavioral burden. It discloses non-obvious semantics (the 'unfinished'/'started' groupings, the high-water threshold defaulting to 0.95, and that results are cached), but says nothing about authorization needs, staleness of the cache, or whether the read is safe/non-mutating.

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 grouped parameter guidance with no filler sentences. The block is somewhat long but every line conveys distinct filter semantics.

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

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

An output schema exists, so return values need not be described. For a 6-parameter, 0%-schema-coverage tool the description covers the semantically hard filters well, though the three remaining parameters (limit, offset, publication) are only implied.

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

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

Schema description coverage is 0%, so the description must compensate and it largely does: it enumerates sort_by values, explains the audience tier concept with a sibling reference, and defines each read_state value precisely. It leaves limit, offset (pagination is only mentioned), and publication unexplained, which keeps it short of a 5.

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

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

States a specific verb+resource ('List cached saved posts') plus the scope of its filters. It doesn't explicitly distinguish itself from the nearby search_saved_posts, though 'cached' and the filter set gesture at the difference.

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

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

It routes the agent to list_audiences for valid audience values, which is genuine usage guidance. However, there is no statement of when to use this versus search_saved_posts or saved_posts_status, so the primary selection decision 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?

With no annotations provided, the description carries the full burden. It discloses the tool is read-only in nature (returns statistics and status) but doesn't state whether it triggers any side effects or has any rate limits. It doesn't describe what 'last sync run status' entails (e.g., success/failure details, timestamps) or what the database path refers to. The description is adequate but not rich in behavioral disclosure.

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 a single, efficient sentence that states the exact content of the return. It is appropriately sized for a zero-parameter tool that retrieves status information, with 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?

Given the tool is simple with no parameters and the output schema exists (though not detailed here), the description covers what the tool does and what it returns. It doesn't explain the format of the output statistics or status, but the output schema presumably provides that. For a status-check tool of this simplicity, the description is mostly complete, though it could benefit from clarifying whether this is a read-only 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?

The tool has zero parameters, so the input schema is empty (schema coverage 100% by default). The description correctly doesn't mention parameters since there are none. Per the rubric, 0 params gives a baseline 4, and the description appropriately focuses on what the tool returns rather than inputs. It adds value by specifying the exact output categories.

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 tool returns three specific pieces of information: cache statistics, database path, and last sync run status. This distinguishes it from the sibling tools that operate on posts or notes directly, since this tool is about system status rather than content.

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 implies a diagnostic or monitoring use case ('Return cache statistics, database path, and last sync run status'), but does not explicitly state when to use this tool instead of other sync-related tools like sync_saved_posts or sync_saved_notes. There are no explicit exclusions or alternatives mentioned, leaving the agent to infer that this is for checking sync status without triggering a sync.

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

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

No annotations are provided, so the description carries full responsibility. It discloses the remote bookmark action, local caching, the authentication prerequisite, the remote_confirmed=False failure state, and the corrective sync behavior—this is substantial and actionable behavioral 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 concise, front-loaded with the purpose, and efficiently uses three sentences to cover action, prerequisite, and failure behavior. No filler or redundancy.

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

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

For a single-parameter tool with an output schema, the description fully covers the essential context: authentication requirement, what the tool does, what failure looks like, and how to recover. Return-value details are unnecessary because an output schema exists.

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

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

The input schema has 0% description coverage and only lists 'url' as a required string. The tool description implies 'url' is a Substack note URL, which adds limited meaning, but it doesn't explain URL format, validation, or any constraints 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 opens with a specific verb ('Bookmark') and resource ('Substack note'), and clarifies the dual action of remote bookmarking and local caching. This clearly distinguishes it from siblings like save_post, unsave_note, and sync_saved_notes.

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

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

The description provides clear usage context: it requires an active authenticated Substack session, mentions what to do if expired, and explains the recovery path when remote confirmation fails. It does not explicitly name alternative tools or say when not to use it, but the intended use is well 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?

No annotations are provided, so the description carries the full burden, and it delivers: it discloses the remote-then-local write pattern, that confirmation comes from Substack's save API or a best-effort button click, and the meaning of remote_confirmed=False (locally cached but unverified). It also names the remediation ('sync --force'), which is exactly the kind of behavioral context an agent needs 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?

Front-loads the core action, then the auth prerequisite, then the confirmation semantics in a logical order. It is slightly long and the confirmation-mechanism detail is dense, but every sentence conveys actionable behavior rather than filler.

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

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

An output schema exists, so return values need no explanation. Combined with the auth requirement, local-vs-remote semantics, and failure/remediation behavior, the description covers everything an agent needs to invoke this correctly.

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

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

Schema description coverage is 0% and there is one required 'url' parameter with no type/format guidance in the schema. The description partially compensates by noting the post's numeric ID is read from the page, implying the input is a post page URL, but it never specifies whether a full URL, slug, or ID is expected.

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 (bookmark/save) and resource (Substack post) plus the dual scope: remote on Substack and local cache. An agent can immediately distinguish it from unsave_post and save_note, which operate on different actions or resources.

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

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

Gives a clear prerequisite and recovery path: requires an authenticated Substack session and tells the agent to run 'substack-saved-mcp login' if expired. It implies the save-vs-unsave dichotomy via naming but never states an explicit when-not or names 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?

With no annotations, the description carries the full behavioral burden and does add real context: it reveals the FTS5 query syntax requirement, the exact searchable fields, and the important limitation that saved_at is always None so saved_after/saved_before are useless. It does not state read-only status or the implicit prerequisite that notes must be synced ('cached') before searching.

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

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

Front-loads the core purpose in the first sentence, then layers in search scope, filter semantics, and the saved_at caveat. Every sentence adds distinct information with no redundancy or filler.

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

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

An output schema exists, so return values need not be described, and the description covers most parameters plus the FTS5 syntax requirement and the saved_at limitation. The gaps are minor: no limit/pagination semantics and no explicit read-only assurance or sync prerequisite.

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

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

Schema description coverage is 0%, so the description must compensate and largely does: it defines query as FTS5 syntax, author as name-or-handle, posted_after/posted_before as ISO 8601 strings, and explicitly explains that saved_after/saved_before match nothing. Only limit is left undocumented, a minor omission given six of seven parameters are clarified.

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 ('full-text FTS5 search across cached saved notes') and further specifies exactly which fields are searched (body text, author name/handle, restack post title). The resource 'saved notes' cleanly distinguishes it from the sibling search_saved_posts, so an agent can select it without opening the schema.

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

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

The description explains capabilities and filter semantics but never says when to prefer this over list_saved_notes or search_saved_posts, nor names any alternative. It does implicitly warn against the saved_after/saved_before filters by noting they match nothing, which is useful but parameter-level rather than tool-selection guidance.

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

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

No annotations exist, so the description carries the burden, and it delivers: malformed FTS5 queries fall back to substring matching, date inputs are ISO 8601, and 'finished' status is defined by a reading-progress threshold defaulting to 0.95. It omits result ordering, pagination behavior, and confirmation of read-only/side-effect profile.

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

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

The core operation is front-loaded and most sentences carry substantive information. It is somewhat long and the read_state parenthetical is awkwardly worded, but there is little outright 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 9 parameters, no annotations, and an output schema that handles return values, the description supplies the semantic detail an agent needs for nearly every filter plus a key behavioral caveat. Missing ordering and pagination guidance keeps it from fully complete.

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

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

Schema description coverage is 0%, so the description must compensate and largely does: it explains query syntax plus fallback, enumerates read_state values with definitions, distinguishes published_at from saved_at, gives audience examples, and specifies ISO 8601 for all date filters. Only 'limit' is left without descriptive meaning, but its default is visible 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 ('Perform full-text FTS5 search across cached saved posts') and names the searched fields (title, excerpt, publication, author, content). This is distinguishable from search_saved_notes and list_saved_posts by resource and mechanism alone.

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

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

Gives real usage context: it routes the agent to list_audiences for valid audience values and warns that content text is only present for posts fetched via get_post_content, implying a prerequisite. It stops short of stating when to prefer list_saved_posts over this search or 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?

With no annotations, the description carries the full burden and does so well: it discloses the early-stop behavior of incremental mode, that force soft-deletes local notes no longer saved remotely, the enumerated SyncRun statuses and their meanings, the truncation/rate-limit case, and the required authenticated session with the login remediation command.

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

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

Front-loads the core action and mode distinction, and every sentence adds real information. The run-on enumeration of statuses is dense but each item earns its place; minor structural tightening would help.

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

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

Complete for a sync tool: auth requirement, both modes, side effects, and failure/partial outcomes are all covered, and although an output schema exists the status enumeration gives an agent what it needs to interpret results.

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

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

Schema coverage is 0% and the single parameter has no description in the schema, so the description must compensate. It does: it defines the default (incremental, early stop) and the full semantics of force=True, including the soft-delete side effect.

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 (resync) and resource (saved notes from Substack into local SQLite cache), with an explicit scope of incremental vs full. An agent can distinguish this from sync_saved_posts and the other siblings 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?

Clearly explains the default incremental mode and when to use force=True (full list plus reconciliation/soft-delete). It does not explicitly name an alternative sibling tool, but the mode-selection guidance is explicit enough for correct invocation.

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

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

No annotations exist, so the description carries the full burden and does so well: it discloses the soft-delete of posts no longer saved on Substack under force, the auth prerequisite plus remediation ('substack-saved-mcp login'), the rate-limiting/truncation behavior reflected in 'partial', and that runs can take minutes. These are exactly the behavioral traits an agent needs and none are derivable from structured fields.

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

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

The core action is front-loaded in the first sentence, followed by mode behavior, return statuses, and prerequisites in a logical order. It is on the longer side and the status enumeration is verbose, but nearly every sentence earns its place given the mutation semantics.

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

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

Even though an output schema exists (so return values need not be documented), the description still names the SyncRun status values and their meanings, which helps the agent interpret partial/auth failures. Combined with the covered prerequisites and side effects, nothing essential for correct invocation is missing.

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

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

Schema coverage is 0% and the single parameter has no schema description, so the description must compensate. It fully explains both values of force: default incremental stops early and leaves older reading progress stale, while force fetches the whole list, refreshes every post, and soft-deletes removed ones. That is richer meaning than the schema's bare boolean-plus-default.

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

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

States a specific verb (resync/sync) and resource (saved posts from Substack into local SQLite cache). The resource is precise enough to distinguish it from the sibling sync_saved_notes and from the read-oriented list_saved_posts. An agent can identify the operation 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?

Explicitly frames the two modes and when to pick each: incremental is the default that stops at already-cached posts, force=True refreshes everything. It does not, however, contrast usage against sibling tools (e.g. when to sync vs. read), so it stops short of the alternative-routing that a 5 requires.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, and it delivers: it explains the soft-delete side effect, what's preserved (note history), what's affected (active search/list outputs), and the meaning of remote_confirmed=False as a partial-failure state. It could add idempotency behavior or error handling, preventing a 5, but this is well above the minimum.

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 core purpose, with each subsequent sentence adding meaningful behavior about soft-deletion and the remote_confirmed flag. Every word earns its place; no fluff or redundancy. This is textbook conciseness without under-specification.

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, low-complexity tool with an output schema, the description covers the essentials: remote action, local cache behavior, and a partial-failure state. Since an output schema exists, the description needn't explain return values, though it could have addressed edge cases like calling on an already-unsaved note or transient network errors.

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

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

Schema coverage is 0% and the description never explicitly explains the url_or_id parameter format or accepted values. However, the parameter name is largely self-descriptive, and the description's mention of remote_confirmed indirectly hints at the identifier's role in the unbookmark operation. A bit more explicit guidance (URL formats, prefix expectations) would justify a higher score.

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+resource+scope: 'Unbookmark a Substack note remotely and soft-delete it in local cache.' It clearly distinguishes from sibling unsave_post by scoping to notes and explicitly describes the dual remote/local action. This matches the 'specific verb+resource+scope' high bar.

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 usage context is clearly implied (use when you want to remove a bookmark from a note), but no explicit when/when-not rules or named alternatives are given. Unlike the calibration example that says 'use search_calls_extensive instead,' this description doesn't guide the agent to an alternative sibling, so it earns a 3 for implied usage without exclusions.

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

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

With no annotations provided, the description fully carries the behavioral disclosure burden. It explains soft-deletion semantics, that remote_confirmed=False indicates local deletion without remote verification, and describes the direct endpoint vs. best-effort DOM click fallback. This is transparent and detailed.

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 information-dense with no filler. The main action is front-loaded, and each subsequent sentence adds essential detail about soft-deletion, remote confirmation, and fallback behavior. The length is justified by the tool's nuanced behavior.

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

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

Despite having only one parameter and an output schema, the description covers the tool's core behavior, failure mode, and local side effects. It explains the remote_confirmed field and points to save_post for the fallback, making the description sufficiently complete for an agent to invoke the 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?

The schema provides only a parameter name 'url_or_id' with no description, and the description does not explicitly define accepted formats. However, the description does add useful context about using the Substack ID when known and the fallback behavior, which partially compensates for the 0% schema coverage.

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

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

The description opens with a specific verb and resource: 'Unbookmark a Substack post remotely and soft-delete it in local cache.' It clearly distinguishes this from sibling tools like save_post and list_saved_posts by describing both the remote action and local cache behavior.

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 on when to use the tool—such as when the post's Substack ID is known after a sync—and references save_post for the fallback DOM-click behavior. However, it does not explicitly state when not to use this tool or compare it to alternatives like delete or list operations.

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