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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the mutation profile is covered structurally. The description adds a compliance/policy warning about spam classification, which is real added context, but it omits what happens on a duplicate address, whether the person is notified, or whether the operation can be undone.

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, both earning their place: the first defines the action, the second delivers a policy constraint. The core action is front-loaded with no filler.

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

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

For a simple 3-parameter mutation with no output schema and full schema coverage, the description is nearly sufficient. A brief note on duplicate handling or the effect of the gift_paid subscription type would make it complete, but nothing essential is missing.

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

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

Schema description coverage is 100%, and the description adds no detail about email format normalization, publication matching, or the free vs gift_paid distinction. Baseline 3 is appropriate when the schema fully documents 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?

States a specific verb and resource ('Add an email address to your subscriber list') that is immediately distinguishable from sibling read/export tools like list_subscribers, export_subscribers, and get_subscriber_count. No ambiguity about what the tool does.

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 second sentence gives an eligibility constraint ('Only add people who asked to be added'), which is useful policy guidance, but it does not name when to prefer an alternative or what to do instead for non-opted-in contacts. Usage is implied rather than explicitly routed.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety and repeat-call profile is covered structurally. The description adds the useful constraint that the tag must already exist (or be created first), but says nothing about permissions, whether re-adding an existing tag errors or no-ops, or what the publication default implies.

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

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

Two short sentences, front-loaded with the action and immediately followed by the prerequisite workflow. No filler or redundant restatement of the title.

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

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

For a simple two-required-parameter mutation tool with full schema coverage and annotations covering the safety profile, the description supplies the one non-obvious thing an agent needs: the id-resolution workflow. The absence of an output schema is not a gap since this operation returns no meaningful payload.

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

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

Schema description coverage is 100%, so all three parameters (tag_id, post_id, publication) are already documented in the schema, including the loose hostname matching and default behavior for publication. The description only reinforces that tag_id must come from list_publication_tags, adding little beyond the schema.

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

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

States a specific verb (put/attach) and resource (an existing tag on a post), which is clear and unambiguous. It does not explicitly distinguish itself from the inverse sibling remove_tag_from_post, but the direction of the operation is evident from the wording.

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

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

Gives concrete prerequisite guidance: call list_publication_tags to obtain the tag id, or create_tag first if the tag doesn't exist. It tells the agent how to satisfy the tool's preconditions, though it never names the inverse operation or states when this tool should be preferred over recreating tags.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower. The description adds one genuinely useful behavioral fact — the state precondition that makes the call fail — but says nothing about what happens to the note afterward (revert to draft, deleted, recoverable) or error behavior.

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

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

Two short sentences, purpose front-loaded and the constraint immediately after; every clause carries information and there is no filler.

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

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

For a one-parameter, no-output-schema tool whose annotations carry the safety profile, the description is nearly sufficient. The only meaningful gap is the post-cancellation state, which an agent might want to know before invoking.

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?

Single parameter with 100% schema description coverage; the schema already documents 'id' including its source ('from list_scheduled_notes'). The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Cancel') and resource ('a queued Note') plus the timing condition ('before it publishes'). An agent can distinguish this from delete_note or unschedule_draft, though the description never names those siblings to make the distinction explicit.

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

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

'Only works while it is still scheduled' gives a clear when-to-use boundary and implicitly a when-not (once published). It stops short of naming alternatives such as delete_note or unschedule_draft for notes that have already gone out.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, so the write/irreversible profile is covered. The description adds genuinely new context beyond that: the comment is published immediately, publicly attributed to the user, has no draft or preview, and is gated behind a confirm flag that is enforced server-side.

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

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

Three short sentences, front-loaded with the action and its public consequence, then the confirm gate. No filler and no restatement of the title.

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

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

For a destructive public write with no output schema and full schema coverage, the description covers the risk profile an agent needs: immediate publication, public visibility, no undo path, and the confirm requirement. It omits only secondary details such as error behaviour or rate limits, which are minor here.

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

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

Schema description coverage is 100%, so post_id, body, parent_id and publication are already documented in the schema; baseline is 3. The description only reinforces the confirm parameter's enforcement ("it refuses to run") without adding syntax, defaults, or constraints beyond what the schema lists.

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 ("Post a comment on one of your posts") and clearly scopes it to the user's own posts. An agent can distinguish it from the read-side siblings get_post_comments, get_comment_thread and delete_comment without inspecting any schema.

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

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

Gives a concrete precondition: no draft and no preview, so the call refuses to run without confirm: true. That tells the agent when the call will succeed or fail, but it names no alternative tool (e.g. for replying to a comment via parent_id, or for reading comments first), so it stops short of explicit when/when-not routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: it warns that returned text is third-party content and must be treated as data, not instructions — an injection-safety note the annotations cannot convey.

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

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

Two sentences, both front-loaded: the value proposition first, then the critical safety caveat. No filler, and the purpose is stated before the caveat rather than buried.

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

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

With no output schema, the description does tell the agent what comes back in shape (posts ranked by engagement), and annotations cover the safety profile. It could say a bit more about aggregation across publications (e.g. whether results are merged or grouped per publication), but for a two-parameter read tool it is largely complete.

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

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

Schema coverage is 100%, with both parameters already documented in the schema including the 1-25 range, default of 10, and the two-to-ten publication constraint. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('pull recent posts from several publications') plus the transformation applied ('rank them together by engagement'), which distinguishes it from single-source siblings like search_posts and research_creator_posts. The clause 'across a whole niche rather than one writer at a time' explicitly differentiates from per-creator research 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 phrase 'so you can see which topics and formats are working across a whole niche rather than one writer at a time' gives a clear situational context for using this over the single-publication alternatives. It stops short of naming a specific sibling tool or stating exclusions, so it is strong but not fully explicit.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower. The description still adds non-obvious context: the draft's visibility is private until published, and the call returns a draft id consumed by every other draft tool — useful for chaining calls.

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

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

Three short sentences, front-loaded with the action, then the privacy behavior, then the return value. No filler and every clause earns its place.

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

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

With a fully documented schema and no output schema, the description supplies the one thing the schema cannot — that the return value is a draft id used by downstream draft tools. Complete enough to invoke correctly, though it could note the template-based alternative.

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

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

Schema description coverage is 100% with 12 richly documented parameters including enums and markdown/body semantics, so the schema carries the full load. The description adds no parameter-level detail, which is the correct baseline of 3 when schema coverage is this high.

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

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

States a specific verb and resource — 'Create a new draft post' — which clearly separates it from update_draft, publish_draft, and delete_draft. It does not explicitly distinguish itself from the very similar create_draft_from_template sibling, so it stops short of a 5.

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

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

The workflow context is implied by 'the draft is private until you publish it,' which hints at the create-then-publish sequence. However, there is no explicit when-to-use guidance, no exclusions, and no pointer to create_draft_from_template as an alternative for templated creation.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the new draft is pre-filled and the template's formatting is preserved exactly rather than reconstructed, which tells the agent the body is a faithful copy. It still omits what happens on an invalid template_id and what the call returns.

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

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

Two tight sentences with no filler, and the core purpose is front-loaded before the formatting-fidelity detail. Every clause carries information.

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

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

With no output schema, the description would ideally tell the agent what a successful call yields (e.g. the new draft id needed for update_draft/set_draft_body) and what happens on failure. For a mutation tool that creates a resource, that return-value context is a meaningful gap, though the creation semantics themselves are adequately covered.

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 75% (title, publication, and template_id documented; subtitle undocumented), which puts the baseline at 3. The description adds no parameter-level meaning such as how publication is resolved or whether subtitle defaults, so it does not compensate for the uncovered 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 states a specific verb (create) and resource (draft) with the key qualifier that it is pre-filled from a saved template's body, which implicitly separates it from the plain create_draft sibling. However, it never names create_draft or list_templates, so the differentiation is left to inference rather than made explicit.

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

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

Usage is only implied: an agent can infer it should call this when a templated starting point is wanted, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. 'use create_draft for an empty draft'). The requirement to first obtain a template_id is only hinted at through the schema's reference to list_templates, not in the description.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds the publication-scoping context and the ordering prerequisite, but says nothing about duplicate-name behavior, failure modes, or whether the created tag is returned.

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

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

Two short sentences, zero waste, with the core action front-loaded and the prerequisite second. Nothing is repeated from the title or annotations.

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

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

For a two-parameter creation tool with complete schema coverage and annotations carrying the mutation semantics, this is sufficient. Duplicate handling and return shape are the only gaps, and neither is required to invoke it correctly.

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

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

Schema description coverage is 100%, with both `name` and the optional `publication` (including its loose hostname matching and default) fully documented in the schema. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a concrete verb and resource ("Create a new tag") scoped to the publication, and the second sentence implicitly distinguishes it from add_tag_to_post by describing the prerequisite relationship. It stops short of naming sibling tools, so an agent must infer the workflow ordering, but the action itself 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?

"A tag must exist before it can be put on a post" implies the use case (create first, then attach) but never states when *not* to use it, nor names an alternative such as checking list_publication_tags first to avoid duplicates. Usage is inferable rather than explicit.

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

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

Annotations already declare this as a non-read-only, non-destructive, non-idempotent, open-world write. The description adds genuinely useful content-layer behavior: the body accepts the same markdown as create_draft, including embeds and a paywall marker. It is silent on permissions, duplicate-name behavior, and whether the template is scoped to a publication, so the added value is moderate.

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, front-loading the action and resource before the body-format detail. Every clause carries information.

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

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

For a write tool with full schema coverage and annotations, the description is nearly adequate, but with no output schema it never says what is returned (e.g., a template id) and gives no guidance on duplicate names or publication scoping. Those omissions matter for correctly chaining into create_draft_from_template.

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 goes beyond the schema by telling the agent that 'body' follows create_draft's markdown conventions including embeds and a paywall marker — semantic constraints the schema's generic 'markdown or HTML' text does not convey.

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

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

States a specific verb and resource: 'Save a reusable post template.' The adjective 'reusable' distinguishes it from create_draft (creates a post), and the cross-reference to create_draft's body format reinforces the boundary. It does not explicitly contrast with siblings like create_draft_from_template, so it stops short of a 5.

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

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

There is no when-to-use or when-not-to-use guidance, and no alternative is named. The only contextual hint is that the body format matches create_draft, which implies a relationship but does not tell the agent when to save a template rather than a draft.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but they do not convey irreversibility; the description adds "Permanent, with no undo" plus the fact that the tool self-guards on confirm, which is behavior an agent cannot infer from the structured fields. It stops short of describing auth requirements 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?

Two short sentences, zero padding, and the destructive nature plus the confirm requirement are front-loaded before any schema reading is needed.

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

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

For a three-parameter destructive tool with full schema coverage, strong annotations, and no output schema, the description supplies the one thing structured data lacks: irreversibility and the refusal-without-confirm behavior. Nothing critical 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 description coverage is 100%, so comment_id, confirm, and publication are already fully documented in the schema, including the publication hostname matching and default. The description reinforces the confirm contract but adds no parameter detail beyond it; baseline 3 applies.

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

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

States a specific verb and resource ("Delete a comment by id") and immediately adds the two facts that matter for a destructive op: permanence and the confirm gate. The agent can distinguish it from delete_note, delete_draft, and delete_template purely from the resource noun.

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

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

Gives a clear precondition for invocation (must pass confirm: true or it refuses to run), which is the key gating rule for this tool. It does not name alternatives or explicitly say when to prefer this over, say, get_comment_thread, but for a deletion endpoint the confirm rule is the operative guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantive context beyond them: irreversibility ('no undo and no trash to recover it from') and a hard guard requiring confirm: true. That is real behavioral disclosure rather than a restatement of the hints.

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, front-loading the destructive nature first and the guard condition second. Every clause carries information; nothing is padded.

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

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

For a destructive mutation with no output schema, the description covers irreversibility, the confirmation requirement, and the target resource. It omits mention of the publication-scoping parameter's default behavior, though the schema documents that, leaving only 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?

Schema coverage is 100%, so the baseline is 3, but the description adds consequence-level meaning for 'confirm' by framing it as a mandatory gate tied to user intent, which the schema alone only partially conveys. It does not add anything for 'id' or 'publication', which the schema already documents 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?

States a specific verb+resource ('Permanently delete an unpublished draft') and scopes it to drafts, which distinguishes it from the sibling delete_note and from update_draft/get_draft. An agent can identify the operation immediately.

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

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

Gives a clear precondition for invocation ('refuses to run without confirm: true') and, via the confirm parameter semantics, ties use to the user explicitly requesting the action. It does not name sibling alternatives (e.g., delete_note), so it falls short of the 5-level routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds genuinely new behavioral facts: the operation is permanent with no undo and it self-gates on the confirm flag. It does not cover authorization requirements or what happens to a scheduled note, so it stops short of a 5.

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

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

Two short sentences, front-loaded with the action and then the irreversible consequence and its guard. Every clause carries information; nothing is padding.

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

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

For a 3-parameter destructive tool with full schema coverage, annotations, and no output schema, the description supplies the safety context an agent needs (permanence, confirm gate). Minor gaps remain around permissions and failure behavior, but 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 100%, so baseline is 3, and the description earns an increment by explaining the semantics of 'confirm' — that its absence causes refusal — rather than just restating the field. The 'id' and 'publication' parameters are left to the already-complete 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 ('Delete ... Notes') with a scope qualifier ('one of your published Notes'), which cleanly separates it from sibling deleters like delete_draft, delete_comment, and delete_template. An agent can identify the correct tool without opening the schema.

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

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

It gives a clear activation prerequisite — the tool 'refuses to run without confirm: true' — which tells the agent exactly what condition must hold before invoking. It does not, however, contrast this tool against the other delete_* siblings or state when deletion is preferable to unpublishing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds non-obvious behavior: the call is hard-gated on confirm:true, and posts previously generated from the template survive the deletion. That scope-of-impact disclosure is genuine value beyond the 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?

Three short sentences, front-loaded with the action, then the safety gate, then the side-effect scope. No filler and nothing that repeats the title.

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

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

For a destructive, non-idempotent tool with no output schema, the description covers the critical unknowns: confirmation requirement, irreversibility, and blast radius. Publication targeting and id format are handled by the schema, so nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the consequence of the confirm flag ('refuses to run') and the permanence rationale, giving the flag meaning beyond the schema's terse 'Set true only when...'.

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 ('Delete a saved template') that cleanly separates it from the delete_note, delete_draft, and delete_comment siblings. An agent can identify the target object 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 states the gating condition ('refuses to run without confirm: true'), which tells the agent when the call will actually execute. It doesn't name an alternative tool for the case where the user wants to remove a draft rather than a template, but the context is otherwise clear.

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

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

Adds substantial behavior beyond the annotations: the asynchronous lifecycle (create set, request, poll, download), a latency expectation, two verified API quirks (tag_ids/group_membership silently dropped and returned in missing_columns, 48 requested yields 46), display-formatted vs raw values, and the absence of paging.

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

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

Front-loaded with purpose and the list_subscribers contrast, then grouped into behavior, verified quirks, and paging. Dense and useful, though the long enumeration of metrics in the opening sentence is slightly heavy.

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

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

With no output schema, the description carries the return-value burden and does so well for an async tool: it explains polling, download, value formatting, and column drops. It stops short of describing the delivered file format or naming the output artifact, which is a minor remaining gap.

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

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

Schema coverage is 100%, so the schema already documents the parameters; the description still adds meaning by clarifying that columns defaults to all exportable ones and that two requested columns can never be returned. It reinforces the AND-only/no-OR filter model, though that is already 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 (export subscribers as full records) and contrasts directly with the sibling list_subscribers, explaining that this is the only way to read engagement metrics the sibling can merely filter on. An agent can distinguish it from list_subscribers without opening either schema.

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

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

Clearly routes the agent: use list_subscribers to filter on engagement metrics, use this tool to actually read them. No explicit 'do not use when' guidance, but the alternative and its selection condition are named.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description still adds real behavioral context beyond structured data: reports covering a period default to the last 30 days, retention defaults to the last year, and limit only applies to 'the reports that take one'.

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 a single framing sentence and a clean bulleted report list where each line earns its place by giving meaning the enum strings lack. The default-window note sits at the very end where it is easy to miss rather than being surfaced with the date parameters.

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

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

With no output schema and 16 report variants, the description carries the burden of describing what comes back, and does so moderately well via the per-report lines plus default date behavior. It stops short of describing response shape (rows vs. timeseries payloads) or pagination beyond the limit cap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema's bare 'Which report to read' by explaining what each of the 16 enum values actually returns, which is exactly the semantic detail needed to pick the right value. The date-window semantics are also elaborated with 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 names a specific verb and resource ('Read one of the publication-level reports behind the dashboard's Stats tabs') and enumerates all 16 report values with a one-line explanation of each, so the scope is unmistakable. It does not, however, differentiate itself from siblings such as get_growth_sources, get_dashboard_summary or get_revenue_summary, and the 'growth_sources' report value in particular overlaps with a sibling tool name without any disambiguation.

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 'reports behind the dashboard's Stats tabs' implies when this tool is the right entry point, and the closing sentence supplies default windows. But there is no explicit statement of when to prefer this over get_dashboard_summary, get_email_stats or get_growth_sources, leaving the agent to infer the boundary.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by flagging that the returned text is third-party content and must be treated as data, not instructions -- a prompt-injection warning absent from the structured fields. It stops short of describing ordering or paging of replies.

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 zero filler; the functional scope comes first and the safety caveat follows. Nothing repeats the name or title, and no sentence is wasted.

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

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

There is no output schema, so the description carries the return-value burden and does so at a high level (a Note plus its replies, authored by others). It omits reply ordering, depth, and any paging limits, which is a minor gap for a simple two-parameter read tool.

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

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

Schema description coverage is 100%, so comment_id and publication are already fully documented, including the loose hostname matching and the default publication. The description adds no parameter-level detail, which is the expected baseline when the schema does the heavy lifting.

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

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

Names a specific verb and resource: reading one Note plus the replies beneath it. The scope is concrete enough to act on, but it does not distinguish itself from the nearby sibling get_post_comments, which could plausibly return similar conversational 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?

Usage is implied by the description (to read a Note thread) but there is no explicit when-to-use, no prerequisite, and no named alternative such as list_notes or get_post_comments. An agent must infer that this is the single-thread read path.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds window-scoping semantics ('start and end of the window') but nothing about permissions, rate limits, or freshness/staleness of the numbers.

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

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

Two compact sentences, front-loaded with the returned metrics and closed with the routing heuristic. Every clause earns its place; no filler.

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

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

There is no output schema, so the description correctly carries the return burden by enumerating the headline figures. Both optional params are fully specified in the schema and all safety hints are in annotations, leaving nothing an agent needs before calling.

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

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

Schema description coverage is 100% with only two optional parameters, both already documented in the schema (range_days window, publication hostname matching). The description adds no format or syntax detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific resource and enumerates the exact headline metrics returned (subscribers start/end, paid subscribers, ARR, recent activity). The phrase 'best single call for how is my newsletter doing' positions it against the many sibling analytics tools (get_analytics, get_revenue_summary, get_subscriber_count) without opening a schema.

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

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

Gives a clear usage scenario ('how is my newsletter doing') that routes the agent here for a general health check. It stops short of naming when NOT to use it or pointing at the more granular siblings for drill-down, so it is context without explicit alternatives 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description adds genuinely useful behavior: the default return format is markdown and why that matters for editing, plus when to ask for prosemirror. It does not discuss permissions or publication resolution, which is a minor gap.

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

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

Three short sentences, zero filler, front-loaded with what the tool returns and why. Each sentence earns its place by covering purpose, default behavior, and escape hatch.

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 3-parameter read tool with full schema coverage and no output schema, the description covers the one thing the schema cannot: the roundtrip editing workflow that motivates the markdown default. Only minor gap is no mention of publication scoping behavior or error cases.

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

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

Schema coverage is 100%, so all three parameters are already documented, including the markdown-editability vs prosemirror-exactness tradeoff. The description adds workflow meaning on top by tying markdown output to feeding update_draft, which is value beyond the schema text.

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 with explicit scope: 'Read one draft in full.' The singular 'one draft' distinguishes it from list_drafts and the mention of update_draft frames it as the read half of a read/write pair, so an agent can place it against siblings without opening schemas.

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

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

The roundtrip framing ('edit a sentence and send it straight back to update_draft') tells the agent when this tool is the right entry point, and 'ask for prosemirror if you need the raw document' gives selection guidance for the format option. It lacks explicit when-not/exclusion language, keeping it at 4 rather than 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint, so the safety profile is covered. The description adds only the metric scope (delivery/open/click) and says nothing about time window, granularity, or whether stats are publication-wide versus per-send, leaving real behavioral gaps.

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

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

One short, front-loaded sentence with no filler; every word contributes to scoping the metrics. It is a verbless fragment, which slightly weakens the action statement, but nothing is padded.

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

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

With no output schema and only one optional parameter, the description should at least indicate the reporting period or return shape, and it does neither. It is minimally adequate for a read-only analytics call but leaves the agent guessing about the time range covered.

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

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

Schema description coverage is 100% and the single 'publication' parameter is fully documented in the schema, including loose hostname matching and the first-publication default. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

The description names the resource (email performance) and enumerates the exact metrics returned: delivery, open rate, click rate. That is specific enough to distinguish it from get_post_stats and get_revenue_summary, though it does not explicitly differentiate itself from the broader get_analytics sibling.

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

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

No when-to-use guidance, no exclusions, and no mention of the alternatives (get_analytics, get_post_stats, get_dashboard_summary) that overlap in scope. The agent must infer from the name alone that this is the email-specific analytics call.

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

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

Annotations already carry the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavior beyond them: results are ranked by source volume, scoped to a time window, and it discloses that this duplicates a get_analytics report — useful for avoiding redundant calls.

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, front-loaded with the outcome, and the second sentence earns its place by justifying the tool's existence relative to get_analytics. No filler.

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

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

With no output schema, the description supplies the essential return shape (sources ranked by subscriber counts) and scoping. It's sufficient for a three-param read tool, though it doesn't say how many sources are returned or whether the list is truncated.

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

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

Schema description coverage is 100% with detailed defaults and format patterns for to_date, from_date and publication, so the schema does the heavy lifting. The description only alludes to a 'window' and adds no syntax or semantics beyond that; baseline 3 applies.

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

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

Specific verb+resource ('where new subscribers came from'), plus the ranking criterion and the window scope. It also explicitly distinguishes itself from get_analytics, so an agent can tell the two apart without opening either schema.

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

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

Names the alternative (get_analytics with the growth_sources report) and explains why this tool exists separately, which effectively routes the agent. It doesn't state when NOT to use it or that it is a narrower slice of the analytics tool, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by disclosing the returned fields (run time, addresses, added, skipped count), compensating somewhat for the absence of an 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?

Two compact sentences with the primary action front-loaded and no wasted wording. Every clause carries information.

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

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

For a simple read-only, one-param tool with no output schema, the description covers return contents and intent well. It omits only edge behavior such as what happens when no import has run yet.

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

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

Schema description coverage is 100% and the single 'publication' param is fully documented in the schema, including loose hostname matching and the default. The description adds no parameter detail, so the baseline 3 applies.

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

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

States a specific verb ('Read the result') and resource ('the most recent subscriber import') and enumerates exactly what is returned. It is clearly distinguishable from subscription-list siblings like list_subscribers or get_subscriber_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?

'Use it to check whether an import actually landed' gives a concrete triggering scenario. However, it names no alternatives and offers no when-not guidance, and no import-initiation sibling exists to route to.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description still adds real behavioral context: it reads the post 'in full' and works against any public publication, not only connected ones. It omits auth/rate-limit details, but that is minor against the 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, zero waste, with the core action front-loaded and the cross-publication capability immediately following. Appropriately sized.

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

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

For a read-only retrieval tool with annotations covering safety and a fully documented schema, the description covers the key ambiguity (cross-publication reads). The remaining gap is the publication vs publication_url distinction, which is left entirely to the schema.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, and the description only reinforces slug as the lookup key. It does not disambiguate the two similar parameters (publication vs publication_url), which is the one place added meaning would help. Baseline 3 is appropriate.

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

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

States a specific verb (read), resource (published post), and lookup key (slug), and additionally declares cross-publication scope ('any public Substack, not just your own'). The 'published' qualifier and 'by its slug' implicitly separate it from get_draft and get_post_by_id, though no sibling is named.

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 a usage scenario ('doubles as a way to read a competitor's post'), which is useful context, but gives no explicit when-not-to-use guidance and never names the adjacent alternatives (get_post_by_id, get_reader_post, scrape_post) that an agent must choose between. Usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description's only added behavioral signal is the word 'published,' hinting that non-published/draft ids may not resolve, but it never states what happens on a miss or whether drafts are excluded.

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 states purpose and the id-vs-slug scope, the second states the trigger. Zero filler and the routing information is front-loaded.

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

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

For a simple idempotent read with a fully documented schema and annotations covering safety, the description supplies what an agent needs to select and call it. The minor gap is the unstated behavior for a draft id or a nonexistent id, though with no output schema this is a small omission.

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

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

Schema description coverage is 100%, so both post_id and publication are already documented in the schema, including the loose hostname matching and the default publication. The description only restates that the id is numeric and adds nothing about the publication parameter, which is the baseline 3 case.

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

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

The description gives a specific verb and resource ('Read a published post by its numeric id') and contrasts the lookup key with the slug-based alternative, which separates it from slug-oriented siblings like get_post. It stops short of naming that sibling explicitly, so an agent must infer which tool the slug path belongs to.

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

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

'Use this when a stats or list tool gave you an id' gives a concrete triggering condition and names the upstream tool families that supply the id. It provides clear context but no explicit when-not or named alternative for the slug case, so an agent still has to infer the inverse route.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the newest-first ordering and an explicit prompt-injection warning that returned text is reader-authored content, not instructions. It stops short of describing pagination behavior or the publication default, so not a 5.

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

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

Two short sentences with zero filler; the resource and ordering are front-loaded and the safety caveat follows. Every sentence earns its place.

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

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

There is no output schema and no annotations gap, so the description needn't explain return values, and the injection warning covers the main non-obvious risk. It does not mention that results are paginated or how offset interacts with limit, a minor omission given the schema covers those fields.

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

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

At 75% schema description coverage, the schema already documents limit (range and default), post_id, and publication (hostname matching), while offset is undocumented. The description adds no syntax, range, or default information beyond that, so it sits at the baseline rather than compensating.

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

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

States a specific verb and resource ('Read the comments on one of your posts') plus a result ordering ('newest first'), which is more than the title restates. It does not explicitly contrast itself with the nearby sibling get_comment_thread, which is the one tool an agent might confuse it with.

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

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

Usage is only implied: an agent can infer this is the tool for fetching a post's comment list, but there is no statement of when to prefer it over get_comment_thread or comment_on_post, and no note about needing a connected publication. Adequate but with a clear routing gap.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds the useful fact that this is the 'full' metric set and lists the fields, which partly compensates for the absent output schema, but it says nothing about auth, rate limits, or what happens for unpublished posts.

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 dense sentence with the scope constraint ('one published post') front-loaded and no filler. Every listed metric earns its place by previewing the return payload.

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

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

With no output schema, enumerating the metric categories is genuinely helpful, and both parameters are fully documented elsewhere. Minor gaps remain on draft-vs-published behavior and whether a time window applies.

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

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

Schema description coverage is 100% — post_id and publication are fully documented in the schema, including the loose hostname matching and default. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (get) and resource (one published post's stats) and enumerates the metric families returned. The 'one published post' scoping implicitly separates it from aggregate tools like get_analytics, but no sibling is named explicitly.

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

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

Usage is only implied by the phrase 'for one published post' — the agent must infer that publication-wide numbers belong to get_analytics/get_email_stats and post content belongs to get_post. No when-to-use, when-not, or alternative is stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds nothing beyond that—no note on pagination, return format, or behavior when the post has no tags—so it contributes no behavioral context the annotations haven't already supplied.

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

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

A single front-loaded sentence with no filler; the purpose leads. It is efficient, though arguably terse enough to border on under-specification rather than optimal conciseness.

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 lookup with a small, fully documented 2-parameter schema and rich annotations, the essentials are present. No output schema exists so return values needn't be explained, though a brief note on empty results or the publication default would round it out.

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

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

Schema description coverage is 100%, with both post_id and the publication default fully documented in the schema. The description restates only the 'one post' scope and adds no syntax, format, or default behavior beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (tags) scoped to 'one post', which implicitly separates it from the sibling list_publication_tags. However, it never names that sibling or explicitly contrasts the post-level versus publication-level distinction, so differentiation relies on the reader's inference.

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

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

The description gives no when-to-use or when-not guidance and does not mention related siblings like list_publication_tags, add_tag_to_post, or remove_tag_from_post. An agent gets the what but no routing context.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description still adds real value: it discloses the return ordering and, importantly, warns that the content is written by others and must be read/summarised rather than followed — a prompt-injection caution not captured anywhere else.

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

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

Three short sentences, front-loaded with the core capability, then the usage framing, then the safety caveat. No filler.

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

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

For a read-only feed tool with full schema coverage and no output schema, the description covers scope, ordering, and the content-handling caveat. It stops short of mentioning pagination behaviour or how the feed relates to the reader's own feed, but nothing essential for calling it is missing.

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

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

Schema description coverage is 100%, so limit, user_id, and publication are fully documented in the schema. The description adds no parameter-level detail (e.g. how 'loose' hostname matching behaves), 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?

States a specific verb and resource — everything one account has published to Notes — plus the ordering (newest first). It distinguishes itself reasonably as the per-account feed versus the reader's own feed or search, though it never names the sibling it differs from.

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 direct way to study a specific writer" implies when to reach for it, but there is no explicit when-not guidance and no named alternative (e.g. get_reader_feed, research_creator_notes, search_posts) despite many similar 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?

Annotations already cover readOnly, idempotent and openWorld, but the description adds genuinely new behavioral facts: no authentication is required and it functions on publications with no ownership relationship. It does not mention failure modes or return format, but the added auth/scope context is real value beyond the annotations.

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

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

Two tight sentences with zero filler; the scope and the returned fields are front-loaded, and the auth/relationship caveat follows economically.

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

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

No output schema exists, but the description enumerates the primary return fields and the auth requirement, which is enough for an agent to call a simple read tool confidently. Minor gaps around the exact response shape and default-parameter behavior remain.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds no parameter-level detail (no mention of hostname matching or the default-to-first-publication behavior), so baseline 3 is appropriate.

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

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

States a specific verb ('Read') and resource ('public details of any Substack publication from its homepage') and enumerates the returned fields (name, description, author, cover image). The 'public' qualifier and 'any publication' scope cleanly separate it from get_publication_settings, which acts on the agent's own publication.

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?

'works on publications you have no relationship with' gives clear context for when this tool applies, and it implicitly contrasts with own-publication tools. It stops short of explicitly naming the alternative (get_publication_settings) or when to prefer search_publications for discovery.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds a useful completeness signal ('everything else on the settings page'), but discloses nothing about auth requirements, rate limits, or return format beyond the field list.

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

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

One sentence, front-loaded with the verb and resource, and the field enumeration is informative rather than filler. It is slightly list-heavy but nothing is redundant.

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

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

There is no output schema, so the description correctly compensates by enumerating the returned settings, which is the key thing an agent needs. For a single-optional-parameter read tool whose annotations cover the safety profile, this is nearly 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 100% and the single 'publication' parameter is fully documented in the schema, including loose hostname matching and the first-publication default. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb ('Read') and resource ('publication's full settings') and enumerates the contents returned. It is clearly distinguishable from mutation siblings like update_publication_settings, though it never explicitly contrasts with the close sibling get_publication_info.

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

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

No guidance on when to use this versus alternatives such as get_publication_info or the sibling update tool. The only contextual note is the parameter default, which is schema-level information rather than usage guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower, yet the description adds genuinely useful context: the returned text is third-party content and must be treated as data, not instructions. This is a prompt-injection disclosure that no annotation conveys. It stops short of describing pagination behavior or return shape.

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

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

Two sentences, zero waste, front-loaded with the resource definition and followed by the single most important caveat. Every clause earns its place.

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

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

For a read-only, open-world feed tool with no output schema and annotations covering the safety profile, the description supplies what an agent most needs beyond the structure: what the feed is and that its contents are untrusted. Missing only pagination/return-size context, which is a minor gap given limit/offset exist in the schema.

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

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

Schema description coverage is 75% and the description adds nothing about tab, limit, offset, or publication. The uncovered 'offset' parameter is documented nowhere in the description, and the description does not explain feed-tab values or the publication-matching rule beyond what the schema already states. Baseline 3 is appropriate when the schema largely does the work.

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

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

The description defines the resource concretely ('The Notes feed, which is Substack's timeline') and states what it returns ('text written by other people'), giving a clear verb+resource reading despite never using an explicit verb like 'read' or 'return' in the operational sense. It does not differentiate from similarly named siblings such as get_profile_feed or list_reader_posts, which an agent could easily confuse it with.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the alternative read tools (get_profile_feed, list_reader_posts, list_notes) that overlap with this one. The only instruction is the safety directive about how to treat the returned content, which is behavioral rather than selection guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description adds three pieces of genuinely new context: the return format (markdown), the fact that paywalled content is included, and an explicit prompt-injection warning telling the agent to treat the text as data, not instructions. That last point is rare and highly valuable for an open-world content-reading tool.

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

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

Three short sentences with zero filler: what it returns first, then the access scope, then the safety instruction. The scope and the injection warning are front-loaded rather than buried, and every sentence carries distinct information.

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

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

With no output schema, the description correctly compensates by naming the return format (markdown) and the content class (other people's text). It stops short of covering failure modes such as an inaccessible or non-existent post, but for a 2-parameter read tool with full annotation coverage the essentials are present.

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

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

Schema description coverage is 100% – both post_id (numeric id from list_reader_posts or a feed) and publication (loose hostname match, defaults to first connected publication) are fully documented in the schema. The description adds no syntax, format, or defaulting detail beyond that, so the baseline 3 applies.

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

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

States a clear verb+resource ('Read the full text of any post') and adds an authorisation scope ('you have access to, including paid posts from publications you pay for') that separates it from public-scraping or own-post tools in the sibling list. It does not explicitly name which sibling to prefer (get_post, scrape_post, list_reader_posts), so an agent must infer the routing from the access-scope wording.

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 the precondition for use (a post you have access to, including paid ones), which implies usage context, but never states when NOT to use it or which sibling to pick instead when a post is your own, public, or a draft. The routing hint to list_reader_posts lives in the schema, not the description, so guidance here is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond that: nothing about time range (all-time vs. monthly), auth or permission requirements, or any scoping/rate constraints for a summary that presumably aggregates financial 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?

One short sentence with no filler, and the resource is front-loaded. It is more of a content enumeration than a purpose statement, but nothing is wasted.

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

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

With no output schema, the description carries the return-value burden and does sketch the shape (tier cost, count, revenue). However, it omits the time dimension the numbers cover and any note on aggregation scope, which matters for a revenue query and leaves the agent guessing about what period the figures represent.

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

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

Schema coverage is 100% and the single optional 'publication' parameter is documented in the schema, including loose hostname matching and the first-publication default. The description adds no parameter meaning on top of that, so the baseline 3 applies.

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

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

The description states the resource (revenue and subscription plans) and enumerates what the result contains: tier price, subscriber count per tier, and revenue. That is clear enough to distinguish it from general listing tools, but it never differentiates itself from other analytics siblings such as get_analytics, get_dashboard_summary, or get_email_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?

There is no when-to-use guidance, no mention of when to prefer this over get_analytics or get_dashboard_summary, and no note about the default publication behavior. The agent must infer applicability purely from the name and sibling list.

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, openWorldHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered externally. The description adds genuine context beyond that: the semantic role of sections and the fact that the returned identifiers feed create_draft/update_draft. It does not disclose return shape or pagination, so not a 5.

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

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

Two sentences, zero filler, and the core purpose is front-loaded ahead of the cross-reference to consumer tools. Every clause earns its place.

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

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

For a simple, annotation-rich list tool with full parameter documentation and no output schema, the definition covers purpose and the key downstream use of section_id. The only mild gap is that it does not describe the shape of the returned list, which an agent might want before formatting 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?

Only one parameter and schema description coverage is 100%, so the schema already explains the loose hostname matching and the default-to-first-publication behavior. The description adds nothing about the publication parameter, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('List the publication's sections') and immediately disambiguates by defining what a section is ('the categories a post can be filed under'), distinguishing it from the tag-related siblings. An agent can tell what it returns 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 second sentence gives an explicit trigger — call this to obtain the section_id required by create_draft and update_draft — which is strong routing guidance to consumer tools. It lacks an explicit 'when not to call' or a statement about alternatives, so it falls just short of the top band.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description usefully clarifies that this returns an aggregate (total plus free/paid breakdown) rather than a subscriber list, but says nothing about freshness/staleness or how the default publication is resolved beyond the schema.

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

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

Two short sentences, front-loaded with the return content before the routing hint, with no filler. Every sentence earns its place.

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

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

For a zero-required-param read tool whose annotations already carry the safety profile, the description tells the agent what it gets back (total, free vs paid). With no output schema, slightly more detail on the return shape or freshness would make it fully self-sufficient.

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

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

Schema coverage is 100% for the single optional 'publication' parameter, including loose hostname matching and the default-to-first-publication behavior, so the description adds no additional parameter meaning. Baseline 3 applies.

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

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

States the resource and exactly what is returned: total subscribers split by free/paid, which is a count aggregation rather than a listing. It does not name the sibling it replaces (list_subscribers, export_subscribers) or otherwise differentiate itself explicitly from them, so it falls just short of 5.

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

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

The phrase "fastest way to answer 'how many subscribers do I have'" implies this tool should be preferred over the subscriber-listing siblings for count questions, which is genuine but indirect guidance. There is no explicit when-not condition and no sibling is named, so usage must be inferred.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds real context beyond them: this reads the session-scoped account and it discloses the returned fields, which annotations do not convey. It stops short of describing auth requirements or behavior when no session exists.

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

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

Two sentences, zero filler. The core purpose and returned fields come first, and the usage guidance follows. Every clause earns its place.

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

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

There is no output schema, so the description correctly compensates by enumerating the returned fields. With annotations covering safety and the schema covering the lone parameter, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and the single 'publication' parameter is fully documented in the schema, including loose hostname matching and the default. The description never mentions the parameter, so it adds nothing here; baseline 3 applies.

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

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

States a specific verb and resource ('Read the account behind the session') and enumerates exactly what is returned: name, handle, user id, bio, owned publications. No sibling tool reads the signed-in account, so it is distinguishable from get_publication_info or get_publication_settings without opening a schema.

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

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

Gives two concrete use cases: confirming which account is connected, and obtaining the user id that other tools require. That is clear selection guidance, though it does not name an alternative tool or state when-not to call 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the list includes roles and user IDs, which is useful, but does not disclose pagination, rate limits, or whether the list includes pending contributors. With annotations present, this is adequate 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 two sentences, front-loaded with the core action and followed by a useful clarification. It is efficient and avoids waste, though the second sentence could be slightly more concise.

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

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

Given the tool's simplicity (one optional parameter, read-only, no output schema), the description covers what the tool returns and why it's useful. It does not explain the return format in detail, but with no output schema, it provides enough for an agent to understand the result.

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

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

Schema coverage is 100%, so the parameter 'publication' is fully documented in the schema. The description does not add any syntax or format details beyond what the schema provides. Baseline 3 applies when schema does the heavy lifting.

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

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

States a specific verb (list) and resource (people attached to the publication) and clarifies the output content (role and numeric user id). It distinguishes itself from siblings like list_subscribers or get_user_profile by focusing on contributors with writing access.

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

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

The description explains the purpose in context ('who a post can be attributed to besides yourself'), which implies when to use it. However, it does not explicitly compare to alternatives or state when not to use it. Still, the context is clear enough for an agent to infer 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds only the default sort behaviour ('most recently edited first'); it says nothing about pagination caps, result size, or auth requirements.

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

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

One short sentence, front-loaded with the resource and scoping, with zero redundant text. Nothing in it could be removed 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?

For a read-only list tool with no output schema and annotation-covered safety, the description is minimally sufficient but leaves gaps: it never clarifies how drafts relate to scheduled posts or posts, and gives no hint about what a draft record contains or how paging behaves.

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 60% (limit, offset, publication documented; the two enums only have defaults), so the baseline of 3 applies. The description's 'most recently edited first' maps to the order_by/order_direction defaults but adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('List unpublished drafts') plus the default ordering, so the agent knows exactly what set is returned. It does not differentiate itself from near-neighbours like list_posts or list_scheduled_posts, so it falls short of a 5.

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

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

There is no when-to-use guidance, no exclusions, and no mention of alternatives such as list_scheduled_posts or list_posts, which an agent could easily confuse with unpublished drafts. Usage is only implied by the word 'drafts'.

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

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

Annotations already establish readOnly, idempotent, openWorld and non-destructive behavior. The description adds genuine context beyond them: the 'newest first' ordering and the 'published' scope, both useful for interpreting results. It stops short of describing pagination behavior or filtering, so a 3 is fair.

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

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

A single, front-loaded sentence with zero waste. Every element (verb, scope, ordering) 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 read-only list tool whose annotations carry the safety profile and with no output schema to explain, the definition is adequate but thin. It omits pagination behavior, the meaning of offset, and how 'published' interacts with drafts or scheduled notes.

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

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

Schema coverage is 67%, below the 80% baseline, so the description should compensate, but it says nothing about limit, offset, or publication. 'offset' has no schema description at all, leaving pagination semantics undocumented in both places.

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

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

The description gives a clear verb ('List'), resource ('Notes'), scope ('you have published'), and ordering ('newest first'). It distinguishes a listing operation from the many note-mutation siblings like publish_note and delete_note, though it doesn't differentiate from list_scheduled_notes or research_creator_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?

There is no explicit when-to-use guidance or mention of alternatives. 'Published' implies it excludes drafts and scheduled notes, but the agent must infer this rather than being routed to list_scheduled_notes or list_drafts.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered. The description's only addition ('newest first') restates an existing schema default, and it omits pagination behavior, whether results are scoped to one publication by default, and any result-size 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?

A single short sentence, front-loaded with the verb and resource. Nothing wasted, nothing buried.

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 5-parameter list tool with no output schema, the description does not explain result shape, total counts, whether paging is required for full coverage, or that publication defaults to the first connected one. An agent could call it, but lacks the context to use paging or scoping 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 mentions only ordering ('newest first'), which the schema already declares via order_by=post_date and order_direction=desc defaults. It says nothing about limit/offset paging or the publication selector, despite only 60% 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?

States a clear verb+resource ('List published posts') plus the default ordering. The 'published' qualifier implicitly separates it from list_drafts and list_scheduled_posts, but no sibling is named explicitly, so the agent must infer the boundary rather than being told.

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

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

There is no when-to-use or when-not-to-use guidance and no alternative is mentioned. With closely related siblings like search_posts, list_drafts, and list_scheduled_posts in the toolset, the absence of routing guidance leaves selection to guesswork.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds real context beyond that: hidden tags are still returned and remain usable on a post even though they are absent from navigation, which an agent could not infer from 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, no filler, and the key downstream dependency (the ids for add_tag_to_post) is stated up front.

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-param read tool with no output schema, the description adequately conveys what comes back (tags plus usable ids) and the hidden-tag nuance. Only minor gaps remain, such as ordering or whether tag names/counts are included.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: it clarifies what 'hidden' tags actually are and why they are still worth retrieving ('usable on a post but not shown in navigation'). That semantic gloss justifies a step above baseline.

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

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

States a specific verb and resource ('List every tag defined on the publication') and points to the downstream usage by naming the sibling 'add_tag_to_post' whose parameter shape it feeds. An agent can distinguish this from get_post_tags without inspecting either schema.

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

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

The description gives a clear reason to call it ('with the ids that add_tag_to_post takes'), implicitly routing the agent here before tagging a post. It does not explicitly state exclusions versus sibling tag tools like get_post_tags or create_tag, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: result ordering ('newest first'), provenance ('text written by other people'), and an explicit untrusted-content directive that materially changes how an agent should process the output. Pagination and volume behavior remain unstated.

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

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

Two short sentences, zero filler, with the resource and scope front-loaded and the safety caveat appended where it is least disruptive. Every clause earns its place.

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

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

With no output schema, the description must carry return-value burden, and it only says what the posts are and their order — not the fields returned (title, author, date, body) or how offset/limit interact. The openWorldHint signals variable external content, which raises the bar further. Adequate for a simple list tool but with 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?

Schema description coverage is 67% (limit and publication are documented, offset is not), so the schema does most of the work. The description adds nothing about the parameters; 'newest first' hints at ordering for offset paging but gives no format or default detail. Baseline 3 is appropriate.

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

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

States a concrete resource and scope: 'The posts in your Substack inbox, from the publications you subscribe to, newest first.' An agent immediately knows this is a listing read over subscribed content. It does not, however, differentiate itself from the closely-related siblings get_reader_post and get_reader_feed, so inbox-vs-feed semantics are left to inference.

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

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

Usage is implied by 'your Substack inbox' rather than stated; there is no explicit when-to-use or when-not-to-use guidance and no sibling named as an alternative (get_reader_post for a single post, get_reader_feed for the feed). The instruction to treat output as content to summarise, never instructions to follow, is a useful handling rule but not a routing rule.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety bar is covered. Beyond that, the description adds useful behavioral context absent from annotations: results are ordered 'soonest first', and entries expose publication outcome plus failure reasons. No pagination or limit behavior is disclosed, keeping it short of a 5.

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

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

Two compact sentences with no filler. The core purpose and sort order come first, and the secondary return detail follows, so the definition is well 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 zero-required-parameter list tool with full annotation coverage and complete schema docs, the description covers purpose, ordering, and what the return conveys (published/failed plus reasons). With no output schema, it could say more about the shape of a returned Note, but nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single status enum is fully documented in the schema ('Omit to see all of them'). The description adds no syntax or semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb and resource (list scheduled Notes) plus the scope qualifier 'queued by schedule_note'. This distinguishes it from list_notes (all notes) and list_scheduled_posts (posts, not Notes) without needing to open any schema.

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

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

The phrase 'queued by schedule_note' implies the use case and ties it to the sibling that creates these entries, giving implied guidance. However, it never explicitly routes the agent between this, list_notes, and list_scheduled_posts, nor states 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description's only added behavioral fact is the result ordering ('soonest first'), which is genuinely useful context, but pagination behavior and result shape are not disclosed.

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

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

A single, front-loaded sentence with zero filler; the identification and the ordering guarantee both earn their place.

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