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

The description states the tool is read-only and that filters compose with AND, but lacks details on authentication, rate limits, or response format. Without annotations, the description carries full burden; this is adequate but not comprehensive.

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

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

The description is concise with three sentences, front-loading 'Read-only' and the purpose. No wasted words, but could be slightly more structured with parameter breakdown.

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 no output schema and 5 parameters with 0% description coverage, the description lacks details on what the response contains or how to use the filters effectively. An agent would need more context for correct invocation.

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

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

Schema description coverage is 0%, and the description only adds that 'Filters compose with AND' without explaining each parameter's values or format. Parameter names like 'kind', 'target', 'status' are self-explanatory but the description does not sufficiently compensate for the missing schema documentation.

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

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

The description clearly states the tool queries the local audit log for write operations, with a specific verb 'Query' and resource 'audit.jsonl log'. It also distinguishes itself from the sibling tool 'dedup_status' which provides a quick count summary.

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

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

Explicit usage guidance is provided: 'Use to debug 'did I post that?' or to pull rate-limit history.' It also tells when to use an alternative: 'For a quick count summary use dedup_status.' This helps the agent select the correct tool.

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

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

Without annotations, the description fully discloses the local file write, use of a local LLM CLI, and the output format with action='proposed'. It also notes the configurable LLM path. This goes beyond just stating it's a write operation.

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

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

The description is concise at two sentences, but the first sentence is dense with parenthetical details, which could be better structured for readability. However, it is front-loaded with the key action.

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

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

The description covers purpose, output, and workflow, but lacks details on parameter constraints (e.g., id format, valid kind values) and does not address error handling or dependencies like required CLI tools, leaving some gaps for an AI agent.

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

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

With 0% schema description coverage, the description adds meaning by explaining kind (post vs note) and out (output file), but it does not specify valid values for kind, format for id, or default behavior for model, leaving gaps.

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

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

The description clearly states it generates reply drafts for comments on a post or replies on a note using an LLM, and writes to a local JSONL file. It distinguishes this from sibling tools like propose_reply and send_approved_drafts by noting it's a local operation and part of a workflow.

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 when to use this tool (for bulk drafting on posts/notes) and mentions the workflow: edit drafts and then use send_approved_drafts. It implies not to use it for single drafts or server-side operations, though explicit alternatives are not listed.

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?

Discloses that it's a write operation, defaults to dry_run=true, and is dedup-protected by (post_id, body) hash. Without annotations, this covers key behavioral traits well, though could mention response behavior or error handling.

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 with no wasted words. The most critical information (action, scope, alternatives) is front-loaded. Every sentence adds value.

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 4 parameters with 0% schema coverage and no output schema, the description is adequate for purpose and usage but lacks parameter details (especially 'pub') and does not describe the return value or error conditions.

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?

Description does not explain parameters beyond the schema. Schema coverage is 0%, so the description should add meaning, but only implies the role of post_id and body via dedup, and ignores pub and dry_run entirely.

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

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

Description clearly identifies the tool as adding a new top-level comment (not a reply), with specific verb 'Add' and resource 'top-level comment'. It distinguishes from the propose_reply/confirm_reply flow for replies.

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

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

Explicitly states when to use (for top-level comments) and when not (for replies), and names alternative tools (propose_reply, confirm_reply). Also notes the default dry_run behavior.

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?

Discloses idempotency (returns deduped: true), force usage, token single-use and 5-minute expiry. No annotations exist, so description carries full burden; it covers major behaviors well.

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

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

Three sentences with key information front-loaded. No verbose or redundant content. Every sentence adds value.

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

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

Covers usage, dedup, token expiry. But does not mention return format for normal success (only idempotent case) or error scenarios. With no output schema, more detail on response would help.

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

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

Schema coverage is 0%, but description explains token as from propose_reply with expiry, and force as bypass for dedup. Adds meaning, though token format could be specified.

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

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

Description clearly states 'EXECUTE the staged write' and details the actions: look up token, post, log, persist. It distinguishes from siblings like propose_reply and comment_on_post by mentioning the token flow and dedup behavior.

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

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

Provides clear context: token from propose_reply, force flag for rare bypass, idempotent behavior. Does not explicitly contrast with alternatives but implies the tool's role in a two-step reply process.

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

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

With no annotations, the description fully covers behavioral traits: read-only nature, data source (SQLite DB), data structure (one row per successful write, keyed by content hash), and no arguments. No missing behavioral context.

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

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

Three short sentences, each adding distinct value: read-only, return contents, health check usage, alternative tool, no args. No redundant or unnecessary 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?

The tool is simple with no parameters and no output schema. The description adequately explains what it does and its purpose. Minor improvement could mention the output format (e.g., counts as integers), but not critical for a health check.

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 has 0 parameters and 100% description coverage. The description adds 'No args' which confirms the empty schema but does not add significant meaning beyond what the schema already shows.

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

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

The description clearly states it is read-only, returns counts from a local dedup SQLite DB, and is a quick health check. It explicitly distinguishes itself from the sibling 'audit_search' for filtered details.

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 direct usage guidance: 'Quick health check; for filtered details use audit_search.' This tells the agent when to use this tool and when to use an alternative.

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?

Discloses destructive nature ('DESTRUCTIVE WRITE', 'Cannot be undone'), ownership requirements, and dry_run safety mechanism. No annotations exist, so description carries full burden and meets it.

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 efficient sentences front-loaded with 'DESTRUCTIVE WRITE.' No wasted words; every clause adds value.

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 no annotations, no output schema, and 4 parameters, the description covers purpose, constraints, parameter behavior, and side effects. A minimal but complete guide for correct invocation.

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

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

Adds meaning for all four parameters: comment_id (implied required), kind (explains values post vs note and implication on pub), pub (needed for post comments), dry_run (default true, must set false to execute). Schema has 0% description coverage; description compensates fully.

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

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

The description clearly states the tool deletes a comment (verb+resource) with ownership constraints, distinguishing it from siblings like react_to_comment or comment_on_post.

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

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

Explicitly states when to use (own comments or owner's publication), warns about irreversibility, and explains how to override dry_run default.

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?

Starts with 'Read-only' indicating no side effects, and describes the return format. Without annotations, this is good but could mention pagination 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 sentences, highly efficient, front-loads the essential info (read-only, purpose), no redundant text.

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

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

Covers purpose, parameters with examples, return fields, and alternatives. Lacks mention of authentication, error cases, or pagination, but acceptable for a simple feed retrieval 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?

Adds meaningful examples for 'tab' parameter (for-you, subscribed, category-slug) and hints at limit affecting list size, but does not elaborate on limit's exact role. Schema has 0% coverage, so description helps but not fully detailed.

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

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

The description clearly states the verb 'Pull' and the resource 'reader feed', and distinguishes from siblings list_posts and search_posts by specifying their use cases.

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 explicit when-to-use instructions with tab options and directs to alternatives: 'For a single publication's chronological list use list_posts; for keyword search use search_posts.'

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

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

Labels tool as 'Read-only', a key behavioral trait. Lists exact keys returned. No annotations provided, so description carries full burden, but could mention any rate limits or side effects; however, for a read-only profile retrieval, the description is sufficient.

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?

Description is succinct (4 sentences) with important information front-loaded: 'Read-only' and 'Return the authenticated user's full profile...'. Every sentence adds value with no redundancy.

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

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

Given the tool's simplicity (no parameters, no output schema), the description fully explains purpose, when to use, what it returns (including key names), and how it differs from a sibling. Complete context for selection and invocation.

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

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

Input schema has zero parameters and schema description coverage is 100%. Baseline is 4. Description explicitly states 'No args', consistent with schema, adding no new information but confirming behavior.

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

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

Directly states the tool returns the authenticated user's profile as a dict with specific keys. Clearly distinguishes from sibling get_profile by specifying alternative for other users.

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 describes when to use ('who am I' calls, preflight checks) and when not to (for other user profiles, use get_profile). Provides context for auth handle needed for WRITE tools.

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

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

Declares 'Read-only' behavior and lists returned metadata fields. Without annotations, it fully carries behavioral disclosure. Does not mention error handling or retrieval semantics, but sufficient for a read operation.

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

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

Two concise sentences with front-loaded 'Read-only' and clear structure. No redundant or vague statements.

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

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

Covers purpose, returned fields, and alternatives adequately. Lacks explanation of the optional 'pub' parameter, but overall sufficient for a simple read tool with no output schema.

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

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

Explains that post_id can be numeric id or slug, but does not clarify the 'pub' parameter at all. With 0% schema coverage, the description partially compensates but leaves an undocumented 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?

Clearly states it returns one post's metadata (title, slug, dates, reactions, comment count) by numeric id or slug. Distinguishes from sibling tools get_post_content and get_post_by_id with explicit alternatives.

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 explicit when-to-use (get one post's metadata) and when-not-to-use (for HTML body use get_post_content; for id-only callers prefer get_post_by_id), along with alternative tool names.

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?

Discloses read-only nature and return shape, but with no annotations, additional details like idempotence or side effects are not explicitly stated, though implied.

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

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

Four sentences, front-loaded with key info, no wasted words. Efficiently conveys purpose, usage, return, and alternatives.

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 single parameter well-explained, return shape described, and correct differentiation from siblings, the description is complete for a simple tool.

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

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

Schema coverage is 0%, but description adds value by clarifying the parameter type (numeric integer), providing an example, and explaining its use context.

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 explicitly states it is a read-only, strict-typed variant that accepts only a numeric post id, clearly distinguishing it from get_post and get_post_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?

Provides explicit guidance: use when caller has integer id for type safety and fewer round-trips; use get_post for slug-or-id input and get_post_content for post body.

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

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

With no annotations, the description carries full burden. It discloses read-only behavior and auth-aware paywall handling, adding significant context. However, it omits details like rate limits, error handling, or side effects.

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 concise sentences, front-loaded with key action. No unnecessary words. Every sentence adds value: first sets context, second adds nuance, third adds optional parameter guidance.

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 no output schema and 3 parameters, the description covers core purpose and auth behavior but not return format or error states. It partially compensates for missing annotations but could be more explicit about output structure.

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

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

Schema coverage is 0%, so description must compensate. It only explains as_markdown (conversion to Markdown for LLM). Post_id and pub parameters are not described, leaving the agent guessing their purpose or format.

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

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

The description clearly states the tool returns a post's body, and specifies read-only nature with auth-aware behavior. It distinguishes from siblings like get_post by focusing on content body rather than metadata.

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

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

The description implies this tool is for fetching post body content, but does not explicitly state when to use it over alternatives like get_post or search_posts. No usage exclusions are provided, and siblings are not referenced.

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

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

Starts with 'Read-only', specifies it's public, and lists exact return fields. Compensates for absent annotations.

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

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

Three concise sentences: purpose, return fields, and usage notes. No redundancy.

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

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

For a simple tool with one param and no output schema, description covers input, output, and usage context fully.

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?

Explains the 'handle' parameter with format and example, adding meaning beyond the schema which has 0% coverage.

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

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

The description clearly states the tool returns a Substack user's public profile by handle, differentiating from sibling 'get_own_profile'.

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

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

Provides explicit guidance: use 'get_own_profile' for own profile (faster, no handle, private fields) and suggests 'list_posts' as next step.

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

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

With no annotations, the description carries the full burden. It clearly states 'Read-only' and explains the filtering logic (filters out branches if user replied). It could add more details like pagination behavior or auth implications, but it sufficiently discloses key behavioral traits.

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 and a brief workflow hint. It front-loads 'Read-only' and the filtering logic, with no unnecessary words. Efficient and well-structured.

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

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

Given no output schema and no annotations, the description covers the filtering logic and use case but fails to document parameters or return format. It provides workflow guidance but not enough for an AI agent to fully understand input semantics.

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

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

The input schema has 0% description coverage, and the description does not explain any parameters (post_id, pub, limit). It relies entirely on parameter names, leaving 'pub' ambiguous. The description should at least clarify the role of each parameter.

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

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

The description clearly states 'Return comments on a post where the authenticated user has NOT yet replied', specifying the verb, resource, and unique filtering. It also distinguishes itself from the sibling tool 'list_comments' by mentioning the alternative for full unfiltered tree.

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 describes when to use it as 'the canonical worklist tool' and provides a workflow: read, draft, propose_reply, confirm_reply. It also advises when not to use it by pointing to 'list_comments' for the full tree.

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

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

The description starts with 'Read-only' to indicate non-destructiveness, and outlines the return structure (parent + replies, fields). No annotations are provided, so the description carries the burden; it covers the key behavioral trait but does not mention potential limitations like pagination 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 sentences, no wasted words. The first sentence is front-loaded with 'Read-only' and the core purpose, followed by a clear alternative in the second sentence.

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

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

The description covers the tool's purpose, scope, and a sibling alternative, but lacks explanation of the 'pub' parameter. For a simple list tool, the context is adequate but not fully complete.

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

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

The schema has two parameters with 0% description coverage. The description does not explain the meaning of 'post_id' or 'pub', leaving the agent to infer from names alone. The 'pub' parameter especially lacks clarity.

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

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

The description clearly states the tool returns 'the full nested comment tree for a post' with specific fields, and explicitly distinguishes it from the sibling tool 'get_unanswered_comments'.

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

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

The description provides explicit guidance on when to use this tool (to get the full tree) and when to use an alternative ('get_unanswered_comments' for unread threads).

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

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

The description explicitly marks the tool as 'Read-only', which is a key behavioral trait. However, since no annotations are provided, it should also disclose other behaviors like pagination, ordering, or what happens if no notes exist. The description adds some transparency but is not comprehensive, earning a 3.

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 extremely concise: three sentences total. The first sentence states the core purpose and read-only nature. The next two sentences provide alternative guidance. Every sentence adds value, and there is no wasted text. It 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?

Given the tool is simple (one parameter, no output schema), the description should fully cover usage. It lacks explanation of the 'limit' parameter and does not describe the output format or any pagination behavior. The absence of these details means the tool is not fully documented for an agent to use 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 does not mention the only parameter 'limit' at all. With 0% schema description coverage, the description should explain the purpose and constraints of the parameter. The agent has no way to know that 'limit' controls the number of notes returned, making this a severe gap.

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

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

The description clearly states 'List the authenticated user's own published Notes (short-form, Twitter-like).' It uses a specific verb ('List'), identifies the resource ('Notes'), and specifies the scope ('authenticated user's own published'). Additionally, it distinguishes from siblings by explicitly saying to use list_comments for comment threads and to fetch via note id for replies, reducing ambiguity.

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

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

The description provides clear guidance on when to use alternatives (e.g., 'For a comment thread on a post use list_comments. For replies under one note, fetch via the note id.'). It implies authentication is needed by stating 'authenticated user', but does not explicitly list prerequisites or edge cases. A score of 4 reflects good guidance with minor omissions.

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

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

The description states 'Read-only' which signals non-destructiveness, but provides no additional behavioral details such as pagination, rate limits, or authentication requirements. With no annotations, the description carries the burden but only partially satisfies it.

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: first sentence defines purpose and default, second sentence lists alternatives. No unnecessary words, front-loaded with key info.

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 listed list tool with 3 parameters and no output schema, the description covers the essential: purpose, default, and when to use alternatives. It lacks details on pagination and parameter format, but given the simple context, it 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 0%, so the description must compensate. It explains the 'pub' parameter implicitly (publication, default yours) but does not clarify 'limit' or 'sort' beyond their names. Some value is added, but not enough for full understanding.

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

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

Description clearly states 'list posts from a publication' with a default scope, and explicitly names sibling tools (get_post, get_post_content, search_posts) for alternative purposes, providing strong differentiation.

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

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

The description includes explicit when-to-use guidance: 'For a single post by id/slug use get_post; for full HTML body use get_post_content; to find by keyword use search_posts.' This helps an agent avoid misuse.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool performs a write (but no Substack call yet), computes a dedup hash, builds the exact payload, stores it under a token, and returns token+preview. It mentions token expiration. It doesn't cover authentication or rate limits, but overall provides good behavioral context.

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

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

The description is four sentences, front-loaded with the core action ('STAGE A WRITE'). Every sentence adds value: validation, hashing, payload building, token storage, preview, approval flow, token expiry, and parameter guidance. No wasted words.

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

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

Given no annotations, no output schema, and 6 parameters, the description covers the essential lifecycle (propose then confirm), parameter rules, and token expiration. It doesn't describe return format or error handling, but those are less critical for this two-phase workflow. It is sufficiently complete for the complexity.

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

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

The input schema has 0% description coverage, so the description must add meaning. It explains that 'kind' determines which IDs are required: 'post' needs post_id and parent_comment_id, 'note' needs note_id. It also clarifies that body is required. It does not explain 'pub' or default values, but the key parameters are well explained.

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 tool stages a write (validate, compute dedup hash, build payload, store under token) and returns token+preview. It distinguishes from siblings by explicitly noting that new top-level comments should use 'comment_on_post' and that approval requires 'confirm_reply' with the same token. This is a specific verb+resource with clear sibling differentiation.

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

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

The description explicitly tells when to use this tool (staging a reply before approval) and when not (for new top-level posts, use comment_on_post). It provides parameter requirements per kind: 'post' requires post_id + parent_comment_id, 'note' requires note_id. It also instructs to call confirm_reply on approval and notes token expiry in 5 minutes.

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?

Discloses dry_run default and idempotency via dedup hash. No annotations exist, so description carries full burden. Missing rate limits or side effects, but sufficient for safe usage.

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

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

Four sentences, each adding essential information. No wasted words, front-loaded with purpose and safe defaults.

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

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

Covers main points: purpose, parameter behavior, alternatives. No output schema, so return value is omitted, but tool is simple enough. Contextual completeness is adequate.

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

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

Schema coverage is 0%, but description explains dry_run parameter (default to true, set to false to post) and implies body is the note content. Could add character limits, but adds value beyond bare schema.

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

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

The description explicitly states the action 'Publish a new top-level Note (short-form post)' and distinguishes from sibling tools like 'reply_to_note' (for replies) and Substack editor (for long-form).

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

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

Clear guidance on when to use alternatives (reply_to_note, Substack editor) and explains dry_run behavior. However, no explicit when-not-to-use or prerequisites.

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

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

No annotations are provided, so the description carries full burden. It discloses that this is a WRITE operation and defaults to dry_run=true, but fails to explain whether it adds/toggles/removes reactions, what happens when 'on' is false, or any permission requirements.

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

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

The description is two sentences and front-loaded with 'WRITE', but it omits needed details. It is not overly verbose, but the brevity compromises clarity.

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 no output schema, no annotations, and 6 parameters with 0% coverage, the description is incomplete. It lacks details about return values, side effects, and parameter behavior beyond kind and dry_run.

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

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

With 0% schema description coverage, the description must compensate. It explains 'kind' and 'dry_run', but leaves 'comment_id', 'reaction', 'on', and 'pub' undefined. This is insufficient for a tool with 6 parameters.

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

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

The description clearly states it is a WRITE action to react on a comment, with a default reaction. It distinguishes between two kinds of comments (post vs note), which helps avoid confusion with sibling tools like react_to_post.

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

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

Provides guidance on setting the 'kind' parameter based on comment type and notes the default dry_run=true. However, no exclusions or alternatives are mentioned, and it doesn't clarify when to use this tool versus similar tools like delete_comment or comment_on_post.

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

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

No annotations provided, so description carries full burden. It discloses default values (reaction=❤, on=true, dry_run=true), the behavior of 'on' parameter (true=add, false=remove), and the dedup/idempotency behavior. Missing explanation of error handling or side effects, but covers key behavioral aspects.

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

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

Three sentences, no fluff. Starts with 'WRITE' to indicate operation type. Every sentence adds value: defaults, sibling alternative, behavioral nuance.

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 toggle tool, description covers core functionality, defaults, and cross-references sibling. Missing explanation of 'pub' parameter and output behavior (no output schema needed). Adequate for typical use.

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

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

Schema has 0% description coverage, so description must add meaning. It explains 'reaction' defaults to ❤, 'on' controls add/remove, and 'dry_run' defaults true. However, 'pub' parameter is not explained at all, and 'dry_run' semantics are implied but not explicit (e.g., what does dry_run do?). Partial coverage.

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

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

The description clearly states 'Add or remove a reaction on a post', specifying the resource (post) and action (add/remove reaction). It also distinguishes from the sibling tool 'react_to_comment'.

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

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

Explicitly says when to use this tool (reacting to a post) and when to use the alternative (react_to_comment for comment-level reactions). Also notes that reactions are not deduped but Substack handles idempotency.

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

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

With no annotations, the description carries the behavioral burden. It discloses WRITE nature, dry_run default, dedup protection, and the safety stack. However, it does not detail the outcome of a successful reply (e.g., auto-publish or draft) or any permissions/rate limits, leaving some 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?

Three concise sentences front-load the action and key behaviors. No redundant words; every sentence adds essential 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 3-parameter tool with no output schema, the description covers core purpose, usage boundaries, and safety features. It omits return/outcome details but is largely 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 0%, but the description adds value by explaining the dry_run parameter's default and the dedup logic tying note_id and body. It does not describe note_id format or body constraints, so it only partially compensates.

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

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

The description clearly states 'Reply to an existing Note (any author's)', specifying the verb 'reply' and the resource 'note'. It distinguishes this tool from siblings like 'comment_on_post' and 'propose_reply' by directing users to those for post comments.

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

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

The description explicitly says 'For replies to a post comment, use propose_reply -> confirm_reply', providing clear when-not use and specific alternative tools. It also explains the dry_run default and dedup behavior, aiding appropriate usage.

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

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

With no annotations, the description fully covers behavior: it indicates a write operation (WRITE), explains the dry_run preview mechanism, and notes the limitation that the on parameter cannot reverse a restack. No contradictions with annotations.

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

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

The description is concise (two sentences plus example and sibling reference) and front-loaded with the action. It efficiently packs essential info but could benefit from slight restructuring for readability.

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 no annotations, no output schema, and a simple tool with three params (0% schema coverage), the description provides complete context: purpose, parameters usage, limitations, and a sibling alternative. An agent has enough to use the tool correctly.

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

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

The description adds meaning to key parameters: dry_run as preview and on as ineffective for false. It includes an example with note_id. While the schema has 0% description coverage, the description compensates well but could clarify note_id format more explicitly.

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

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

The description clearly states the tool's action ('restack a Note') and its effect ('broadcasting it to your subscribers' feeds'). It also distinguishes from the sibling tool 'restack_post' by specifying that this is for short-form Notes and that tool is for long-form posts.

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

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

The description provides explicit usage guidance: defaults to dry_run=true as a preview, must set dry_run=false to actually publish. It also warns that Substack does not support un-restacking (on=false is a no-op), which is critical for correct 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?

Discloses that Substack does not support unrestacking, making the irreversible nature clear. Also explains the default dry_run behavior, beyond what annotations provide (none).

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

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

Four concise sentences, each adding value. Front-loaded with action and purpose. No unnecessary words.

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

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

Covers purpose, usage guidelines, behavioral traits, and sibling link. Missing output description but acceptable for a write tool with no output schema.

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

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

Although schema coverage is 0%, the description adds critical context about defaults (dry_run, on) and the fact that setting on=false is ineffective. It does not explain post_id format but compensates with behavioral nuance.

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

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

Description clearly states 'WRITE. Restack a post (Substack's reshare).' It uses a specific verb-resource combination and distinguishes from restack_note.

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

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

Explicitly mentions default dry_run=true and the irreversibility of restacking. Also directs to restack_note for notes, providing clear alternatives.

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

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

No annotations provided, but description itself states 'Read-only' and describes return format (titles+ids). Could mention pagination or rate limits, but overall good for a search 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?

Two concise sentences, front-loaded with 'Read-only' and purpose. No wasted words.

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

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

Covers purpose, usage, and return format. Lacks parameter details for 3-param tool with no output schema. Adequate but has clear gaps.

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

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

Schema coverage is 0% (no descriptions in schema), yet description does not explain individual parameters like query format, limit usage, or pub meaning. Only implicit mention of query via full-text search. Does not compensate for low schema coverage.

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

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

Description clearly states tool is for full-text search of posts ('search_posts'), specifies it is read-only, and distinguishes from sibling 'list_posts' for chronological browsing.

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

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

Explicitly says use for keyword discovery, not for chronological browsing (use list_posts). Also notes that results are only titles+ids and suggests calling get_post/get_post_content for details.

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?

Given no annotations, the description adequately discloses behavioral traits: it is a write operation, it skips certain rows, honors throttle, defaults to dry run, and has a force option for dedup bypass. It does not mention idempotency or side effects on the drafts file, but covers the main mutation behavior.

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

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

The description is concise and well-structured, using short sentences to convey key information. Every sentence adds value: the action, filtering, throttle, and flags. No redundant or vague phrasing.

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

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

The description covers the tool's functional behavior well, but lacks information about the return value (e.g., success count or errors). Given the complexity of iterating over a file and posting, details on error handling or status reporting would improve completeness. The absence of output schema increases the need for such info in the description.

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

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

With 0% schema description coverage, the description adds significant meaning beyond defaults: it explains that 'drafts_path' is the file to process, 'dry_run' defaults true, 'force' bypasses dedup, and 'rate_seconds' controls throttle. Three of four parameters are clarified, though 'drafts_path' is only implied.

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

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

The description clearly states the tool's purpose: to sequentially post approved drafts from a specific file. It uses a specific verb ('post') and resource ('drafts.json entries'), and distinguishes from sibling tools like 'bulk_draft_replies' by specifying the filtering and sequencing behavior.

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

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

The description provides good usage guidance, including which entries are processed (approved only), the throttle behavior (rate_seconds), and the dry_run and force flags. It implies when not to use (for proposed/rejected entries) but does not explicitly list alternatives or when to choose this over siblings like 'confirm_reply'.

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?

Marks itself as read-only, which is critical behavioral information. With no annotations provided, the description carries the full burden and adequately communicates the tool's non-destructive nature. No additional behaviors like rate limits need mention for this simple test.

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 succinct sentences, each adding value. Front-loads 'Read-only' and states purpose, usage, and arguments efficiently. No wasted words.

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

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

For a simple test tool with no parameters and no output schema, the description covers purpose, usage, and return value completely. It is self-contained and leaves no ambiguity.

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?

Input schema has zero parameters, and description confirms 'No args.' This adds clarity beyond the schema, which is implicit. Baseline for 0 parameters is 4, and the description fulfills this.

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

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

Description clearly states the tool verifies a Substack session cookie and returns specific user details (id, handle, primary publication). This verb+resource combination is distinct from sibling tools, which perform different actions like searching or commenting.

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 advises calling this tool when other tools return 401 or to confirm setup. While it gives clear guidance on when to use, it does not mention when not to use or provide alternatives, but the context is sufficient for a diagnostic tool.

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