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

The description adds substantial behavioral context beyond the annotations: it changes future email distribution, default dry-run behavior, welcome email delivery is unverified, it never grants paid access or overrides suppression, existing members are skipped, and automated callers must persist an attempt ledger before invoking. These are non-obvious effects an agent could not infer from readOnlyHint or destructiveHint alone.

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

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

The description is dense but every sentence earns its place: it opens with the core operation, then covers side effects, consent requirements, dry-run behavior, failure handling, and cross-session persistence. There is no filler or repetition.

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

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

Given the tool has an output schema and five parameters including nested consent evidence, the description is complete: it covers prerequisites, side effects, reconciliation, duplicate protection, and non-idempotency. Nothing needed for safe 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 description coverage is only 20%, and the description compensates by explaining dry_run, send_welcome_email, and the consent requirement. consent_evidence already has its own schema description, and email is self-explanatory. The description therefore adds meaning to the most behavior-critical parameters even though not every parameter is individually discussed.

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: 'Add one explicitly opted-in reader to this publication's free newsletter.' It also scopes the operation to free access and explicitly says it 'Never grants paid access,' which distinguishes it from any subscription or payment-related sibling tool.

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

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

The description gives concrete usage rules: requires verified newsletter consent, never infer consent from a meeting, dry-run by default with dry_run=false to write, and existing members are skipped. It also names the right reconciliation path: 'An unverified result MUST be reconciled using get_subscriber, not automatically retried.'

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

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

Annotations only indicate readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds meaningful behavioral context beyond that: it accepts markdown and converts it to Substack's format, and it creates a draft without publishing. This helps the agent understand side effects and scope without contradicting the annotations.

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

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

Two tight sentences with no filler. The primary action and the most important caveat ('Does NOT publish') are front-loaded, and the markdown conversion detail 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 create tool with five parameters, a full output schema, and annotations covering the safety profile, the description is sufficient: it names the resource, the format conversion, and the non-publishing behavior. It could be slightly more complete by explicitly distinguishing from update_draft, but that gap is minor.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning to the body parameter ('converted to Substack's format'), which enriches what the schema says. It doesn't detail every parameter, but the schema already covers those well.

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

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

The description states a specific action ('Create a new draft post') on a specific resource, and explicitly distinguishes it from publishing by saying 'Does NOT publish — creates a draft only.' The word 'new' also differentiates it from sibling tools like update_draft and export_draft.

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

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

The description clearly implies when to use the tool: to create a draft rather than publish. It also states an explicit exclusion ('Does NOT publish'). However, it does not explicitly name alternatives such as update_draft for existing drafts or create_note for notes, so it stops short of full routing guidance.

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

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

Beyond the annotations, the description discloses critical behavioral traits: it PUBLISHES IMMEDIATELY, Notes have no draft state, and this server has no delete tools, making the action irreversible. This is valuable context that annotations alone do not 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 focused sentences: the first states the core action, and the second delivers the essential consequence (immediate, irreversible publishing). Every phrase earns its place and the key warning 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?

For a single-parameter tool with an output schema and annotations present, the description covers the essential decision factors: what it creates, that it publishes publicly, that there is no draft or undo path, and that markdown is supported. No critical calling information 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 input schema already fully documents the only parameter 'body' with 'Note content in markdown format'. The description adds only 'Accepts markdown text,' which does not meaningfully expand on the schema. With 100% schema coverage, a baseline 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 uses a specific verb and resource: 'Create a Substack Note (short-form content).' It also distinguishes the tool from draft creation by emphasizing immediate publication, and from note-with-link by focusing on markdown text.

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 conveys that this tool publishes immediately and that Notes have no draft state, so an agent can infer it is for public short-form content rather than drafts. It does not explicitly name alternatives like create_draft or create_note_with_link, but the context is strong enough to guide 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?

The description explicitly discloses important behavior beyond the annotations: PUBLISHES IMMEDIATELY to a public feed, no draft state, and no undo from the server. This is valuable because annotations only say the tool is not read-only and not destructive; they do not convey irreversibility or public visibility.

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

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

Two tight sentences with no wasted words. The main purpose is front-loaded, followed by the critical publishing warning. The formatting with caps draws attention to the most important behavioral caveat without adding bulk.

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 tool with a complete schema and an output schema present, this description provides everything needed to call it correctly: what it does, how it behaves, when it publishes, and the lack of undo. No critical operational gap remains.

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

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

The schema already covers both parameters with 100% coverage, so the baseline is 3. The description adds meaning by explaining the presentation relationship: the link is shown as a rich card below the note text, which clarifies how the url and body parameters interact beyond their individual schema descriptions.

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

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

The description states a specific verb ('Create'), a specific resource ('Substack Note with a link attachment'), and the key differentiator: the link is displayed as a rich card below the note text. This clearly separates it from the sibling create_note and other note-related tools.

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

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

The context is clear enough: use this to publish a note with a link attachment, and it publishes immediately. However, it does not explicitly say when to prefer this over create_note, nor does it state exclusions like 'for plain text-only notes, use create_note instead.' The reference to 'same caveats as create_note' implies the relationship but does not provide explicit routing guidance.

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

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

The description clearly states there are no writes, URL fetching, or local file access, and mentions it makes two read-only API calls. It also provides output bounds and security guidance, going well beyond the readOnlyHint 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 dense but organized: it leads with the primary purpose, then covers behavioral constraints, edge cases, security, and limits. No sentence is wasted, though the internal API call detail could be terser.

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

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

The description covers purpose, side effects, output behavior, security considerations, and performance bounds. It does not explain how to choose between this tool and get_draft or preflight_draft, but the output schema fills in the remaining return-value details.

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 draft_id with an integer type and no description. The description mentions 'draft identity' but does not explicitly define draft_id; however, the parameter name is self-explanatory enough for an agent to infer its meaning.

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

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

The description clearly states the tool reads a draft as editable Markdown plus detailed metadata and body information. It does not explicitly differentiate from sibling tools like get_draft, but the purpose is specific enough.

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 useful guidance about read-only behavior, partial export behavior, and treating exported text as untrusted, but it does not explicitly say when to use this tool instead of alternatives like get_draft or preflight_draft.

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

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

Annotations already declare readOnlyHint=true, and the description's 'Get' is consistent with that. The description adds limited behavioral context by mentioning return contents, but it does not disclose behavior for missing drafts, authorization needs, or any additional side effects. No contradiction with annotations.

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

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

The description is one concise sentence with no wasted words. It front-loads the verb and resource, then provides the useful scope ('full content') and return fields, making it easy to scan.

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-only tool with one fully documented required parameter and an output schema present, the description is almost complete. It lacks an explicit pointer about when to choose this over closely related siblings like export_draft or list_drafts, but that gap is minor given the clarity of the rest.

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 parameter, already stating 'The draft ID to retrieve'. The description's 'by ID' adds no new semantic meaning beyond the schema, so the baseline 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 clearly states the specific verb ('Get'), resource ('draft post'), and selection criterion ('by ID'), and further specifies 'full content' with return fields ('title, body, metadata'). This distinguishes it from siblings like list_drafts, get_post, and export_draft.

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

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

The description implies when to use the tool: when the agent has a draft_id and needs the full content of a specific draft. However, it does not explicitly name alternatives or exclusions, such as when to prefer list_drafts or export_draft, so guidance is only implicit.

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

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

The annotation indicates readOnlyHint, which covers the read-only nature. The description adds a constraint that the post must be published, but does not disclose other behavioral aspects such as error handling or side effects. Given the presence of the annotation, this is adequate but not exceptional.

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, consisting of a single sentence that states the action and the expected return data. It is well-structured and front-loaded, making it easy to parse.

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 retrieval operation, the description is sufficiently complete: it names the input and output content. It does not address error cases or edge conditions, but given the simplicity and the presence of an output schema, this is not a significant 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 input schema fully describes the only parameter (post_id) with a clear description. The tool description does not add any additional meaning to this parameter, so a 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 clearly states the tool's function: retrieving the full content of a published post by ID, and explicitly mentions the returned data (title, body HTML, metadata). It distinguishes itself from sibling tools by specifying 'published post', making its purpose unambiguous.

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

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

The description implicitly provides usage guidance by specifying that it operates on published posts, which contrasts with draft-related tools. However, it does not explicitly mention alternatives or when to prefer this tool over others, so it falls short of a 5.

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

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

The description goes far beyond the readOnlyHint annotation by disclosing the lack of a native per-post stats endpoint, the 500-post search behavior, the not-found note variants, and the concurrency caveat ('concurrent publishing or deletion can hide a post'). It also explains the stats_available false case, giving the agent a realistic model of failure modes 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 front-loaded with the core action and resource, then adds only high-value behavioral caveats and edge cases. Every sentence earns its place: the metrics list, the search workaround, the concurrency warning, and the stats_available clarification. It is dense but not bloated.

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 and the presence of an output schema, the description is remarkably complete. It covers the operation, the underlying limitation, the search bound, failure conditions, concurrency risks, and the meaning of stats_available. An agent has enough information to invoke it correctly and interpret unusual outcomes.

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 already documents post_id with a clear description and 100% coverage. The description adds no new parameter-specific meaning beyond referring to 'by ID', so the baseline of 3 applies. There is no gap for the description to fill.

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: 'Get performance stats (views, emails sent/delivered/opened, signups, subscribes, estimated value, comments, reactions) for a published post by ID.' This unambiguously states what the tool does and lists the metrics. It also clearly distinguishes itself from siblings like get_post and get_post_comments by focusing on analytics rather than content or comments.

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 establishes when to use the tool: when you need performance stats for a published post by ID. It does not explicitly name alternatives or state when not to use it, but the context is unambiguous. The mention of 'published post' helps differentiate it from draft-related siblings.

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 readOnlyHint annotation already covers the safety profile, and the description mentions returned data rather than side effects. However, it does not disclose behaviors such as pagination, ordering, or possible empty results, so transparency is adequate but not 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 compact and information-dense, with exactly two sentences and no redundant phrasing. Every word contributes to understanding the tool's purpose or output.

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 operation, the description sufficiently identifies the required post_id and the returned fields. The absence of an output schema is partially mitigated by listing expected fields, though details like sorting or pagination behavior are not mentioned.

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 fully documents both parameters, including constraints, defaults, and descriptions. The tool description adds no additional semantic nuance beyond what the schema already provides, so this dimension is at 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?

Clearly states the action ('Get'), the resource ('comments on a published post'), and the returned fields. The qualifier 'published' helps distinguish from draft-related sibling tools, making the purpose immediately identifiable.

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?

Provides no explicit guidance on when to use this tool versus alternatives, no named sibling tools, and no conditions or exclusions. The only contextual hint is 'published post', which is implicit rather than actionable 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 only provide readOnlyHint: true, so the description carries the behavioral disclosure burden. It goes far beyond that by revealing hidden tag inclusion, unresolved ID preservation, pagination limits, non-atomic multi-read behavior, and the caveat that empty or draft associations have verification limits. This is exemplary transparency.

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 dense but efficient: every sentence adds a distinct piece of actionable information, and the core action is front-loaded. Caveats are packed without 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?

Given an output schema exists to describe return values and annotations declare read-only safety, the description fills the remaining gaps: pagination semantics, transactional behavior, hidden tags, and edge-case verification limits. An agent has enough context to correctly invoke this tool and interpret unusual behavior.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning to limit and offset with 'Returns 25 rows by default, at most 100, with local snapshot pagination', and post_id is implied by 'by post ID'. It does not exhaustively bind every parameter, but it covers the non-obvious runtime 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?

The description opens with a specific verb-resource pair: 'Read tag associations by post ID', and clarifies it resolves names from tag definitions, includes hidden tags, and preserves unresolved IDs. This clearly differentiates it from siblings like list_publication_tags or get_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 makes the usage context clear: call this when you need tag associations for a specific post. It also states what the tool will not do ('Never assigns or removes tags'), which helps avoid using it for mutations, though it does not name alternative sibling tools explicitly.

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 annotation indicates readOnlyHint, and the description reinforces this by stating 'No changes are made.' It additionally reveals verification behavior and how missing API fields are handled, providing useful behavioral context beyond the 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 brief and to the point, consisting of two sentences that cover the purpose, verification, and read-only nature 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?

Given the simple nature of the tool (no parameters, read-only), the description provides enough context about what it reads and how it behaves. It could mention the output format, but the description already notes that missing fields are named explicitly, which is helpful. Overall, it is complete for its complexity.

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

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

The schema has no parameters, so all parameters are documented (none). The description does not add parameter-specific information, but this is not needed. Baseline 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 clearly states the tool's function: reading projected identity and selected settings for the publication. It uses a specific verb ('read') and identifies the resource ('publication'), distinguishing it from sibling tools that deal with posts, drafts, or 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 does not explicitly mention when to use this tool over alternatives, but it provides context about what it verifies (host) and what it does not (account identity, admin role). This gives some implicit guidance, but lacks explicit comparison to sibling 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?

The annotation already declares readOnlyHint=true, and the description adds that it returns id and name, which is consistent and sufficient. No contradictions.

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

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

Two concise sentences: first states purpose and output, second gives usage guidance. No unnecessary 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 list tool with no parameters and no output schema, the description fully covers what the tool does, returns, and how to use 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?

No parameters exist, so schema coverage is 100%. The description does not need to add parameter explanations, meeting the baseline for 0 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 clearly states the verb 'list' and the resource 'sections', and it distinguishes itself from sibling tools by focusing on listing categories.

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 provides explicit guidance on using the section ID for drafts, which is the primary use case. However, it does not mention when not to use it, but that is acceptable for a simple list 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 declare readOnlyHint, and the description adds material behavioral caveats: a listed free subscriber counts as a member, absence may be due to suppression or lag, and absence does not prove ineligibility. These go well beyond the annotation and help the agent interpret results correctly.

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 earning its place: core lookup, membership semantics, data caveats, and usage. The main action is front-loaded; only the word 'Read-only' is redundant with the annotation, which is negligible.

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 one-parameter read-only lookup. Output schema covers return shape, and the description covers matching behavior, data reliability caveats, and the intended reconciliation use case. Nothing needed to call it correctly is missing.

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

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

With 0% schema description coverage, the description compensates by specifying 'exact email address,' which clarifies matching semantics beyond the schema's email format and maxLength. For a single self-describing parameter, this is sufficient.

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 action ('Look up a subscriber') with an exact-match criterion on email address, which distinguishes it from sibling listing tools like list_subscribers and get_subscriber_count. The resource and lookup semantics are 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?

Gives a clear usage context: 'use to reconcile uncertain adds.' It does not explicitly name alternatives or state when not to use it, but the exact-email lookup and reconciliation purpose are enough for an agent to select it appropriately.

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 readOnlyHint annotation already indicates this is a read-only operation. The description adds valuable behavioral context by explaining the precision field (exact/approximate/unavailable) and the explicit warning 'Never treat an approximate value as exact.' This goes beyond the basic 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 concise and front-loaded with the primary purpose. It includes necessary detail about precision handling but is slightly verbose with the example and repeated caution. However, it remains focused and easy to parse.

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

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

The description sufficiently covers the return value nuances, including all possible precision values and the meaning of count -1. While an output schema is indicated as present, the description alone provides enough context for typical usage. It does not mention error cases or edge conditions beyond the precision, but these are minor 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, and the input schema is an empty object. There are no parameter semantics to explain, so the description is fully sufficient. Schema coverage is 100% by definition.

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 action: 'Get the current subscriber count for your Substack publication.' It also explains the output precision semantics, making the purpose unambiguous. It distinguishes itself from sibling tools like list_subscribers or get_subscriber by focusing specifically on the aggregate count.

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 does not provide any guidance on when to use this tool versus alternatives. It does not mention any conditions or contrasts with sibling tools like list_subscribers or get_subscriber, leaving the decision to the agent to infer.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful context by specifying the returned fields, which matters since there is no output schema. However, it does not disclose behavioral details like ordering, whether draft content/body is omitted, or pagination effects beyond what the schema already covers.

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 short sentences with no filler. The first sentence gives verb and resource, and the second states the output shape. Every word contributes 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 simple read-only list tool with fully documented optional parameters, this description is largely complete: it names the return fields even though no output schema exists. It could mention ordering or the lack of full draft content, but those are not essential for basic correct invocation.

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

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

The input schema has 100% description coverage: both limit and offset have meaningful descriptions. The tool description itself adds no parameter-level semantics, 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?

The description states a specific verb and resource ('List draft posts') and enumerates the returned fields (title, creation date, audience). It is distinguishable from list_scheduled_posts by the word 'drafts', but it does not explicitly contrast itself with get_draft or export_draft.

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

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

There is no guidance on when to use list_drafts versus siblings like list_scheduled_posts, get_draft, or export_draft. The description only says what the tool does, with no conditions, exclusions, or alternative routing.

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

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

The description goes well beyond the readOnlyHint annotation by disclosing default row counts, maximum rows, local pagination behavior, the two reads per call, potential inconsistency between calls, validation behavior, and the explicit guarantee that it never creates or assigns tags. This is exemplary transparency.

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 core purpose, then adds behavioral details in a logical order. Every sentence carries useful information with 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?

Given the output schema exists and the annotations provide the read-only guarantee, the description covers defaults, limits, pagination semantics, consistency caveats, validation, and side-effect absence. Nothing critical is missing for an agent to invoke 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?

The description explains default row counts and maximum rows, which map to limit, and mentions hidden tags by default, which maps to include_hidden. However, offset is not explicitly described; the mention of local pagination and changing results implies its behavior but does not fully compensate for the 0% schema description 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: 'Read this publication's tag definitions.' It clearly identifies the operation and scope, and the detail about including hidden tags by default differentiates it from related tag tools like get_post_tags.

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 'this publication's tag definitions' gives clear context for when to use the tool, and the sibling list confirms there is a distinct get_post_tags tool for post-level tags. It does not explicitly name alternatives or exclusions, but the resource distinction is clear enough.

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 readOnlyHint annotation already covers safety; the description adds output details but does not go beyond that, so limited additional transparency.

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

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

Two concise sentences, no fluff, and the key purpose 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?

With an output schema present and a clear mention of return fields, the description is complete for the intended use.

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?

Both parameters (limit and offset) have clear, detailed descriptions including clamping behavior, with full 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?

Clearly states the action ('List published posts') and resource, distinguishing it from similar tools like list_scheduled_posts.

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

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

Provides clear context on pagination and return fields, but does not explicitly mention alternatives or when to prefer this over search_posts.

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 readOnlyHint annotation is true and the description reinforces it by stating the tool does not schedule, publish, or delete posts. This fully discloses the tool's side effects (none).

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 and front-loaded with purpose and read-only nature. It avoids fluff and clearly states the return fields, making every sentence valuable.

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 without an output schema, the description lists what is returned (id, title, audience, scheduled time). Combined with the read-only note and parameter descriptions, an agent has enough context 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 complete descriptions for both parameters (limit and offset), so the baseline is 3. The description adds no extra parameter-specific information 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?

Clearly states the verb 'List' and resource 'posts scheduled for publication', with the ordering 'soonest first'. The read-only note and reference to scheduling in the editor distinguish it from sibling tools like list_published_posts and list_drafts.

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

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

Explicitly says 'Read-only visibility into what's queued' and that scheduling itself is done in Substack's editor, clarifying when not to use this tool. It also mentions no publishing or deletion, providing clear boundaries.

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 readOnlyHint annotation is reinforced by the non-destructive 'Read' wording. The description adds useful behavioral context about privacy and potential lag without contradicting the 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?

Two short, focused sentences with no redundant wording. Every clause adds value: the action, the data privacy, the lag caveat, and the alternative tool.

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

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

Output schema exists, so output fields need no description. The privacy warning, lag caveat, and alternative-tool pointer give sufficient operational context for a straightforward paginated read 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?

limit and offset are not explicitly described, but the phrase 'Read a page' combined with the schema's defaults and bounds makes their pagination role clear enough. Slight extra explanation would be needed for full clarity, but the intent is unambiguous.

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?

Description clearly states the operation ('Read a page'), the resource ('subscriber email addresses and subscription IDs'), and the privacy scope. It also distinguishes this from get_subscriber by directing exact membership checks there.

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

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

Explicitly tells agents when not to use this tool ('Use get_subscriber for exact membership checks') and warns about data lag, giving practical context for approximate/bulk membership listing.

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

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

The description goes well beyond the readOnlyHint annotation by adding 'No writes,' explaining the receipt binding observed state, and disclosing limitations: 'Hashes check consistency, not human approval; stale detection is best-effort, not atomic.' This is strong behavioral context that helps an agent trust and interpret the result.

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

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

The description is compact and front-loaded with the core purpose in the first sentence. Each sentence adds value, though the list 'bounded previews, conversion losses and preflight' is jargon-heavy and slightly awkward.

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

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

The safety profile, no-write guarantee, receipt semantics, and consistency caveats are well covered, and an output schema exists to describe return values. However, with 6 parameters and zero schema descriptions, the lack of parameter guidance is a real gap, and the relationship to preflight_draft 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 description coverage is 0%, so the description carries the burden of explaining parameters, but it never mentions draft_id, allow_unsupported, audience, or subtitle. 'Markdown/metadata changes' loosely hints at body/title/subtitle but doesn't clarify the important flags or defaults.

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 reads/reviews an unpublished draft and proposed Markdown/metadata changes, and it distinguishes itself from update_draft by explicitly saying 'No writes' and returning a receipt for update_draft. However, the word 'preflight' overlaps with the sibling preflight_draft, so it doesn't fully separate itself from that tool.

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

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

The phrase 'exact payload for update_draft' plus 'No writes' establishes clear context that this is a planning/preview step before updating a draft. It doesn't provide explicit when-not guidance or name alternatives such as preflight_draft or get_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?

The description fully discloses that the tool is read-only and non-destructive, aligning with the readOnlyHint annotation and adding concrete details about what it does not guarantee.

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, well-structured in three sentences, and covers the essential aspects without unnecessary verbosity.

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?

It provides sufficient context about what the tool does, its limitations, and where to review results (Substack), making it complete given the 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 only parameter, draft_id, is not described in the schema (0% coverage) and the description does not explicitly explain it beyond the tool's context, so it only partially compensates for the missing 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 clearly states the tool reads a draft and checks specific aspects (title, audience, body structure, images, paywalls), making its purpose 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?

It explicitly notes it is a static review aid that never modifies or publishes, and it clarifies limitations (no rendering/link/publish guarantees), guiding appropriate usage.

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 readOnlyHint annotation, the description adds critical behavior: it returns default/max rows, supports pagination via total and next_offset, passes values through unmodified, does not recompute metrics, and explains that null/absent are distinct from zero. These details prevent an agent from assuming the tool cleans or infers data.

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 and front-loaded with the core purposeable immediately actionable. Every sentence contributes substantive value—purpose, pagination, read safety, data fidelity, null semantics, and sibling routing. The only minor redundancy is "One read; nothing is changed," which is short and reinforces rather than bloats.

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 output schema exists for return valuesстоит, the description covers everything needed to call the tool correctly: parameter meanings, defaults, limits, pagination, behavioral caveats, and alternative tool routing. It is complete enough for agent invocation without further inference.

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

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

With 0% schema description coverage, the description carries the full burden. It enumerates every metric enum value, explains the limit default and maximum, conveys offset continuation semantics through next_offset, and clarifies sort direction. It also provides important caveats about rate denominators and null handling that the schema alone could 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?

The description opens with a specific verb and resource: "Rank posts by one metric from Substack's dashboard email statistics." It enumerates the exact metrics and sort directions, making the tool's purpose unambiguous. The final sentence explicitly distinguishes it from get_post_analytics, which is the closely related sibling for single-post stats.

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 states the intended use case—ranking multiple posts by a dashboard metric—and explicitly routes single-post stats to get_post_analytics. This gives the agent a direct decision rule for choosing between the two most similar 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?

Beyond the readOnlyHint annotation, the description discloses pagination behavior ('One page per call, at most 50 results'), continuation via 'next_offset', server-controlled indexing limitations, and metadata-only return values. These details set accurate expectations about how the search behaves and what it cannot guarantee.

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

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

The description is three tight sentences with no filler. The main scoping is front-loaded, followed by pagination caveats and the metadata-only/content-fetching distinction.

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 presence of an output schema and readOnly annotations, the description covers everything needed to call the tool correctly: scope, statuses, pagination limits, continuation mechanism, and search-quality caveats. The minor offset/next_offset wording ambiguity is resolvable from the input 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?

With 0% schema description coverage, the description compensates by explaining page size, pagination continuation, and the published/draft/scheduled statuses. However, it references 'next_offset' without explicitly mapping it to the schema's 'offset' parameter, and it leaves limit defaults to the schema's own constraints.

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

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

The description names a specific action ('Search'), a precise resource ('this publication's published, draft, or scheduled archive'), and the mechanism ('Substack's server-side query'). It also explicitly distinguishes itself from content-fetching tools by stating 'Returns metadata only; get_post/get_draft fetch full 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 routes full-content needs to get_post/get_draft and clarifies that search is not a guaranteed full-text scan. It does not explicitly contrast search_posts with the list_* siblings, so an agent must infer when to choose query-based search over simple enumeration.

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/read-only flags, it discloses the pre-PUT recheck, single PUT plus read-back, stale/changed-payload rejection, the remaining read/write race, and the need to inspect conflict outcomes manually. No contradiction with annotations.

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

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

Every sentence carries distinct operational information: precondition, verification, mutation, race, retry policy, format, and non-side-effects. 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 destructive, race-prone update tool, the description covers preconditions, safety checks, failure behavior, retry prohibition, and side-effect boundaries. Output schema handles the return shape, so nothing needed 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?

With 0% schema description coverage, the text explains the crucial receipt contract (unsigned consistency receipt, not approval), ties all editable fields to 'exact changes reviewed' in the plan, and notes Markdown support. It leaves audience and allow_unsupported implicit, but the plan-dependency makes their meaning recoverable.

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 precise action ('apply exact changes reviewed with plan_draft_update') and resource (draft), and explicitly excludes publishing/scheduling. This makes it immediately distinguishable from create_draft, plan_draft_update, and scheduling siblings.

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

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

It states the required precondition (receipt from plan_draft_update), clarifies that the receipt is not human approval, and tells the agent never to auto-retry. This is concrete when-to-use and when-not-to-act guidance tied to a named sibling.

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

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

Annotations only set flags (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds substantial behavioral context: the hosted URL is 'publicly fetchable by anyone with the link' and 'an unlisted asset — not attributed to you or added to your feed'. It also discloses important security details for `image_url` (sent without cookies, refusal of private/loopback destinations, redirect limit of 3). This goes well beyond what 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 compact but information-dense. The main action and the 'exactly one' rule appear in the first sentence, followed by necessary clarifications in parentheses. No fluff, but the parenthetical about `image_url` security is a slight digression; still, it's essential context. Overall well-structured.

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

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

The tool has three mutually exclusive parameters, security constraints, and an output schema (which describes the return value). The description covers the input requirements, behavior, and return (hosted URL) sufficiently. There is no missing information that would prevent an agent from invoking 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?

The schema already describes each parameter at 100% coverage. The description reinforces mutual exclusivity and adds practical constraints for `image_url` (5 MB, 15 seconds, type matching) and for `image_path` (MIME inferred from extension). This adds value beyond the schema without redundancy.

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?

Description states a specific verb ('Upload') and resource ('image to Substack's CDN'), which is clear and distinct from all sibling tools (export, get, list, create, etc.). No ambiguity about what this tool accomplishes.

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 explicitly mandates 'Provide exactly one of' the three input modes, which is a clear usage rule. It also notes that `image_url` is 'Not available on every deployment' and includes mutual-exclusivity language. However, it does not explicitly state when to prefer this tool over alternatives, though no sibling upload tool exists, so that gap is minor.

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