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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the check action but fails to mention what the tool returns (e.g., boolean, error), whether it has side effects, or how it behaves on missing slugs. This is a minimal disclosure that leaves key behavioral aspects unspecified.

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

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

The description is a single concise sentence that directly states the purpose. It is front-loaded, contains no unnecessary words, and avoids 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 (one parameter, no output schema), the description is minimal. However, it omits critical information such as return type, error handling, and usage context, especially since annotations are absent. This makes it incomplete for an agent to call 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 single parameter 'slug' has no schema description (0% coverage), and the tool description does not define what a slug is or its expected format. The description only mentions 'book slug' without elaboration, so it adds little meaning beyond the parameter name itself.

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 ('Check') and resource ('book slug exists and you are an author'), which clearly conveys the tool's purpose. However, it doesn't explicitly differentiate from sibling tools like get_book, but the intent is clear enough for a simple check tool.

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

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

The description implies this tool is used to verify existence and authorship before operations requiring authorship, but it doesn't explicitly state when to use it versus alternatives like get_book or create_book. No 'use this when' or exclusion guidance is provided, leaving usage context inferred 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?

With no annotations provided, the description must carry the full behavioral burden, but it only mentions that the book becomes hidden and that only the primary author can perform the action. It does not disclose whether closing is permanent or reversible, what happens to existing readers/royalties, or any other side effects of the 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 a single front-loaded sentence with no filler. The core verb, resource, effect, and permission are packed efficiently.

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 and no output schema, the description is too sparse to fully support correct invocation. It lacks clarification of the slug parameter, reversibility, return behavior, and how it differs from the closely related sibling tools unpublish_book and retire_book.

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 one parameter (slug) with zero description coverage, and the tool description does not mention the parameter at all. The meaning of 'slug' may be inferable, but the description adds no explicit semantic value beyond the schema.

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

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

The description states a specific action ('Close a book completely') and its observable effect ('hidden from the store'), making the tool's purpose reasonably clear. It does not explicitly contrast this with sibling tools like unpublish_book or retire_book, so it earns 4 rather than 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?

No guidance is given about when to choose close_book over unpublish_book or retire_book, and no exclusions or alternative conditions are mentioned. The only constraint, 'primary author only', is a permission note rather than a decision 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?

With no annotations, the description carries the full burden of behavioral disclosure. It only states that a new book is created, without revealing side effects, what the created book's initial state is, whether publishing is required separately, or any job/async behavior. This is a minimal disclosure for a mutation 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 a single front-loaded sentence with no filler or repetition. It is concise and to the point, though extremely short; the lack of detail is more a completeness issue than a conciseness issue.

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 an 8-parameter creation tool with no annotations, no output schema, and only 13% schema description coverage, this description is far from complete. It omits parameter meanings, mode-specific requirements, return behavior, and post-creation implications, leaving the agent to guess critical details.

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

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

Schema description coverage is only 13%, and the description adds almost no parameter meaning. The mode names ('Browser, GitHub, or Upload') loosely map to syncMode but do not explain the values or dependencies like githubPath, which is only described in the schema. With 8 parameters and only one documented in the schema, the description fails to compensate.

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 a specific resource ('a new Leanpub book'), and further distinguishes the tool by listing the modes (Browser, GitHub, or Upload). This clearly separates it from sibling tools like create_bundle, create_course, and create_track.

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 guidance on when to use this tool versus alternatives, nor does it explain when each mode should be chosen. It only implies that this is the tool for creating books, but offers no exclusions, prerequisites, or comparison with related create_* 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description merely restates the create action already implied by the tool name and does not explain side effects, idempotency, required permissions, validation behavior, or what the API returns on success or failure.

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

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

The description is a single, focused sentence with no filler, redundant wording, or unnecessary detail. It front-loads the action and the target resource clearly.

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

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

For a tool with no annotations, no output schema, and three undocumented parameters, a one-sentence description is far from complete. An agent lacks essential information about required inputs, expected values, and the result/return behavior needed to invoke the tool correctly.

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

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

Schema description coverage is 0% and the schema properties have no descriptions. The description does not explain the meaning of title, slug, or publisherId, or clarify which parameters are required and how they should be formatted.

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

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

The description uses a specific verb and resource: 'Create a new Leanpub bundle.' It clearly distinguishes this tool from the sibling create tools by naming a distinct product type (bundle vs. book, course, track).

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

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

No guidance is given on when to use create_bundle versus create_book, create_course, or create_track. It also does not mention any prerequisite conditions, such as whether a publisher or existing book/course is required before creating a bundle.

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 at all, the description carries the full burden of behavioral disclosure. It only says "Create a new coupon" and does not mention side effects, duplicate handling, date validation, read/write implications, or what happens when required fields are missing. For a creation tool, this is a significant transparency gap.

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

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

The description is concise and front-loaded, but it is under-specified. It is a single sentence with no fluff, yet it lacks almost all useful detail an agent needs, so its brevity is not an asset here.

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 8 parameters, 4 required fields, no output schema, and no annotations, this one-line description is far from complete. It does not state return behavior, required field semantics, date formats, uniqueness constraints, or how coupon creation relates to the book resource.

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

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

Schema description coverage is only 38%, so the description must compensate, but it adds no parameter-level meaning. It does not explain couponCode, discountedPrice, startDate, maxUses, slug, note, or how "for a book" maps to packageSlug or slug. The only hint is the word "book," which is too vague.

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 clear verb and resource: "Create a new coupon for a book." It distinguishes this tool from siblings like list_coupons, get_coupon, and update_coupon by signaling creation rather than retrieval or modification.

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

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

No guidance is given about when to use this tool versus alternatives, nor any prerequisites or exclusions. An agent must infer from the tool name that this is the creation path, and there is no mention of conditions such as uniqueness of couponCode, required book existence, or relationship to packageSlug.

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 present, so the description carries the full burden of behavioral disclosure. It only restates the create action and provides no information about side effects, permissions, uniqueness constraints, or what happens after a course is created. This is a significant gap for a mutating tool.

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

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

The single sentence is short and front-loaded, but the tool has 8 parameters and no annotation or schema descriptions. This is under-specification rather than earned conciseness, since it omits information an agent needs to invoke the tool correctly.

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 an 8-parameter, mutating tool with no annotations and no output schema, a one-sentence description is completely inadequate. The agent is left without parameter semantics, behavioral consequences, return behavior, or guidance on when this tool is appropriate.

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 names none of the 8 parameters. The agent must rely on property names like slug, syncMode, githubPath, publisherId, previewBranch, and publishBranch without any explanation of their meaning, format, or relationships.

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 and resource: 'Create a new Leanpub course.' The resource is identified specifically enough to distinguish from book, bundle, and track creation at a basic level. However, it does not elaborate on what a course is or how it differs from those sibling 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?

No when-to-use guidance is provided. The description does not mention alternatives, prerequisites, or conditions under which create_course should be selected over siblings like create_book, create_bundle, or create_track.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only indicates that a new track is created, with no mention of side effects, validation behavior, required permissions, idempotency, or response details.

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

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

The description is a single clear sentence with no fluff, and the key resource definition is front-loaded. It is appropriately concise for the amount of information it conveys, though it could be more informative without becoming verbose.

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

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

For a mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is too sparse. It explains what a track is but omits parameter guidance, usage context, and behavioral expectations, leaving an agent without enough information to invoke the tool confidently.

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 provides no information about the parameters (slug, title, publisherId). The parenthetical defines 'track' but does not explain any parameter meaning, required fields, or constraints.

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

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

The description uses a specific verb and resource ('Create a new Leanpub track') and clarifies what a track is with the parenthetical 'curated collection of courses.' This makes the tool's purpose clear, though it does not explicitly differentiate it from sibling tools like create_bundle or create_course.

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

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

There is no guidance on when to use this tool versus alternatives such as create_course or create_bundle. The description only states what the tool does, leaving the selection context entirely to inference.

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

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

With no annotations, the description carries the full burden of disclosing side effects, auth requirements, and error behavior. It merely lists returned fields and uses the verb 'Get', implying a read, but it does not mention whether a valid slug is required, what happens for missing books, or any authentication 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?

The description is a single sentence that leads with the action and resource, then lists the returned fields with no filler. It is well-structured and easy to parse, conveying maximum information in minimal space.

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

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

The tool is simple (one parameter, no output schema), and the description explicitly lists the returned fields, which helps an agent construct a request. However, it omits failure behavior, prerequisites (e.g., using check_book_exists first), and any output structure details, leaving notable gaps for an agent to handle correctly.

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

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

Schema coverage is 100%; the slug parameter is already documented with a description and example. The tool description adds no additional parameter details beyond referencing 'a book', and the schema already provides sufficient semantics.

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

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

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('a book's summary'), and enumerates the exact fields returned (title, word/page counts, sales, download URLs). This distinguishes it from sibling getters like get_royalties or get_coupon without needing to inspect 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?

No guidance is provided on when to use this tool versus alternatives such as preview_book, check_book_exists, or get_royalties. The description only states what it does, leaving the agent to infer selection criteria.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does reveal the consent/opt-in filter, but it does not mention whether this is a read-only operation, whether authentication is required, how errors are handled, or what happens when no readers have shared emails.

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. Every word adds meaning, and the key qualifier ('who opted to share them') is included without extra explanation.

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 single-parameter getter with no output schema or annotations, the description is adequate for an initial call but lacks return-format details, error behavior, and any mention of pagination or authorization. Enough to invoke, but not enough to fully set expectations.

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 0% description coverage and the description never mentions the 'slug' parameter. The agent must infer that slug identifies the specific book from the tool name and description. No format, example, or clarification is provided.

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

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

The description uses a specific verb ('Get'), a clear resource ('emails of readers of a specific book'), and an important qualifying condition ('who opted to share them'). This clearly distinguishes it from sibling tools like get_user_reader_emails and get_interested_readers.

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 purpose implies when to use the tool: when you need the emails of readers for a specific book and the readers have opted in. However, it does not explicitly contrast with any sibling tools or state when not to use it, leaving some room for inference.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It doesn't mention whether the coupon must exist, what happens if not found, whether it's a read-only operation, or any rate limits or auth requirements. The description is too thin to inform an agent about side effects or failure modes.

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

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

The description is a single short sentence with no wasted words. It's front-loaded with the verb and resource. However, it's so brief that it sacrifices useful context.

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

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

For a tool with no annotations, no output schema, and 0% schema description coverage, the description is inadequate. An agent doesn't know what 'details' includes, what the return format is, or how this differs from list_coupons. The tool is simple, but the description still leaves critical 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 0%, and the description doesn't explain what 'slug' or 'couponCode' mean or how they relate. The parameter names are somewhat self-explanatory, but the description adds no value beyond the schema, and the required combination of both parameters is unexplained.

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 clear verb ('Get') and resource ('details for a specific coupon'), which distinguishes it from list_coupons and create_coupon. However, it doesn't explicitly differentiate from update_coupon or other coupon-related tools, and 'details' is somewhat generic.

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 tool versus alternatives like list_coupons or get_book. The description implies a lookup use case but doesn't state when it's appropriate or what distinguishes it from sibling tools.

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

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

With no annotations provided, the description must carry the behavioral transparency burden. It does disclose a read-only intent ('Get') and the response shape ('paginated list'), but it says nothing about error cases, authentication requirements, rate limits, or what data is excluded from the list. The disclosed behavior is minimal but at least non-misleading and partially informative.

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

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

The description is a single, grammatically tight sentence with no filler. It front-loads the action and resource, which is good. However, it could have used the limited word count to add a brief parameter or usage note without becoming verbose, so it is concise but not optimally informative.

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 annotations, no output schema, and 0% schema description coverage, the description is the only source of guidance. It fails to explain the required slug, the optional page and email parameters, the meaning of 'individual purchases,' or any pagination details. It is adequate as a label but insufficient 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 mentions none of the three parameters (page, slug, email). It vaguely says 'for a book' but does not map to slug, and it entirely omits the meaning of email and page. An agent cannot infer parameter semantics from either the schema or the description, making it nearly impossible to call correctly without external knowledge.

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 ('Get') and resource ('a paginated list of individual purchases for a book'), which generally distinguishes it from siblings like get_royalties or get_book_reader_emails. However, the term 'individual purchases' is not elaborated, leaving some ambiguity about what counts as an individual purchase versus other financial or reader data.

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 guidance on when to use this tool versus alternatives. It does not mention related tools such as get_royalties for financial summaries or get_user_reader_emails for reader contact data, nor does it state conditions that would make this tool the correct choice. The agent must infer usage entirely from the tool name and generic phrase.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool lists readers, implying a read operation, but doesn't disclose whether it requires authentication, whether it returns paginated results, what the response format is, or any side effects. For a read tool with no annotations, this is a notable gap.

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

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

The description is a single, concise sentence that front-loads the core action and resource. It earns its place with no filler, though it could add a bit more context without becoming bloated.

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

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

The tool has one required parameter with zero schema coverage, no output schema, and no annotations. The description is too sparse to fully guide an agent: it doesn't clarify what 'slug' means, what the response looks like, or how this relates to sibling tools like get_user_reader_emails. Given the low complexity (1 param), a bit more detail would make it 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 for the undocumented 'slug' parameter. The description doesn't explain what 'slug' refers to (e.g., book slug, course slug, or interest slug), leaving the agent to guess. This is a significant gap given the single parameter is required.

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

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

The description clearly states the tool lists readers who registered interest and opted to share their email. It uses a specific verb ('list') and resource ('readers who registered interest'), and the qualifier about email opt-in distinguishes it from a generic reader list. It doesn't explicitly name a sibling, but the purpose is clear enough to differentiate from tools like get_user_reader_emails or get_book_reader_emails.

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 the tool is for retrieving interested readers who have opted in, which gives some context. However, it doesn't explicitly state when to use this over alternatives like get_user_reader_emails or get_book_reader_emails, nor does it mention any exclusions or prerequisites. The usage context is implied but not fully articulated.

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

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

With no annotations provided, the description is solely responsible for behavioral disclosure. It does disclose a key behavior (returns {} when no job is running), which adds value. However, it does not state whether the operation is read-only, what happens when a job is running (e.g., status fields), or any potential side effects or delays. This is minimal but non-contradictory.

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

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

The description is two short sentences, front-loading the main action and including the key return behavior. It is concise with no filler, and the structure is easily scannable.

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 parameter, no output schema), the description is still incomplete. It fails to define the 'slug' parameter, describe the return format when a job is running, or note any prerequisites (e.g., whether the job must already be initiated). The lack of annotations and output schema increases the burden on the description, which it does not meet.

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 one required parameter 'slug' with no description, and the description does not explain what 'slug' refers to (e.g., the job's slug, book slug, etc.). With schema description coverage at 0%, the description must compensate, but it provides zero parameter semantics. An agent cannot confidently know what value to provide.

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 checks the status of a running preview/publish job and notes the empty return when no job is running. It names the specific resource ('job') and the action ('check status'), which is unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'wait_for_job', which is a closely related operation.

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

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

No guidance is provided about when to use this tool versus alternatives. For instance, it doesn't clarify whether this should be used for polling or snapshot checks, nor does it mention 'wait_for_job' for blocking behaviors. The usage context is entirely absent.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It implies a read operation by using 'Get', but it does not disclose whether it requires API key verification or other permissions, whether it aggregates data from multiple sources, or what the response format looks like. These gaps leave the agent uncertain about side effects or dependencies.

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

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

The description is a single concise sentence, front-loaded with the verb and resource. It has no wasted words and is easy to scan, though it could benefit from a brief note on the 'slug' parameter or return format without losing 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?

Given the tool's complexity (single parameter, no output schema), the description is minimal but misses critical context: what the summary includes (e.g., revenue breakdown), any prerequisites like a valid book slug, and how it differs from purchase-level data. An agent might call it with incorrect assumptions about the response format.

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

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

The only parameter, 'slug', is documented in the schema only as a string type, with no description. The tool description mentions 'a book's' but does not clarify that 'slug' likely refers to the book's unique identifier. With low schema coverage (0%), the description should clarify that 'slug' is the book identifier, but it only implies it through context, so it 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 states a clear verb ('get') and resource ('book's sales and royalties summary'), and 'sales and royalties' distinguishes it from the sibling 'get_book' and 'get_individual_purchases'. However, it does not explicitly explain why it differs from 'get_individual_purchases' or how the summary is aggregated, which would fully differentiate it.

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

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

The description gives no guidance on when to use this tool versus alternatives like 'get_individual_purchases' or 'get_book'. There is no mention of prerequisites (e.g., book must exist, user must have access) or context clues for the agent to decide between this and similar read 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?

With no annotations, the description carries the behavioral burden. It usefully discloses the privacy constraint ('readers who opted to share them with you') and the cross-book/course scope. However, it does not mention authentication, response format, rate limits, or errors; for a simple getter this is a moderate but acceptable 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?

A single front-loaded sentence with no filler. It states the action, the resource, and the scope compactly.

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

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

For a two-parameter tool with no output schema and no annotations, the description should map parameters to behavior and differentiate from siblings like get_book_reader_emails and get_interested_readers. It establishes scope but leaves type semantics and sibling boundaries largely implicit.

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

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

Schema description coverage is 0%, so the description must compensate, but it never explains the required username parameter or the type enum (all/book/course). The phrase 'across all your books/courses' hints at scope but does not clarify how type filters results. An agent would be uncertain what value to pass for type.

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

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

The description names a specific resource and action: 'Get emails of readers who opted to share them with you'. The scope 'across all your books/courses' clearly differentiates this from sibling get_book_reader_emails, which is likely scoped to a single book.

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

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

The description gives clear context for when to use it: whenever reader emails are needed across all books or courses. It does not explicitly name alternatives or exclusions, but the cross-library scope strongly implies this is the aggregate counterpart to book-specific 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?

With no annotations, the description carries the full burden. 'List all coupons' transparently communicates a read-only retrieval of a collection, but does not specify ordering, filtering, or whether inactive coupons are included.

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. It states the core action and object immediately and earns its place without redundancy.

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

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

For a tool with no annotations, no output schema, and one undocumented parameter, the description is too thin. It lacks parameter semantics and any detail about return value or behavior, leaving an agent to guess.

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

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

Schema description coverage is 0%, and the description does not explain the slug parameter, its format, or how it maps to the book. The word 'book' hints at the context but does not explicitly define slug.

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

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

The description uses a specific verb ('List') and resource ('all coupons for a book'), and distinguishes from sibling get_coupon by scope (all vs one). The purpose is immediately clear.

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 guidance on when to choose this over related tools such as get_coupon, create_coupon, or update_coupon. The only implied usage is the action itself, so the 'vs alternatives' dimension is unaddressed.

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 discloses the key behavioral trait: the operation is asynchronous ('Returns immediately') and instructs the agent on how to track completion. This is essential context for an agent to avoid blocking or misinterpreting the return. It does not cover failure modes or side effects, but the core behavior is well communicated.

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

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

The description is a single, front-loaded sentence that packs the essential facts: what it does (starts full preview), the outputs (PDF + EPUB), the async nature ('Returns immediately'), and how to get results (poll or wait). Every phrase earns its place; no filler or redundancy.

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

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

For a one-parameter async trigger with no output schema, the description covers the immediate interaction flow: initiate and then poll. It does not mention prerequisites (e.g., book must exist) or error handling, but given the sibling tools like check_book_exists and the simple parameter, this is reasonably complete. The main omission is the lack of slug explanation, but that is more a parameter-semantics issue.

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 one required parameter 'slug' with no description, and schema description coverage is 0%. The description does not explain what 'slug' refers to or its expected format, leaving the agent without guidance beyond the raw type 'string'. Since the description should compensate for the schema's lack of detail, this is a notable 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 the verb 'Start' and resource 'a book', and specifies the scope as 'full preview generation' with formats 'PDF + EPUB'. This distinguishes it from siblings like preview_subset and preview_single, though it doesn't explicitly name them. The purpose is unambiguous and task-focused.

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

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

The description implies usage for full previews by specifying 'full preview generation', but it does not explicitly state when to choose this over preview_subset or preview_single. It does provide operational guidance on monitoring completion via get_job_status or wait_for_job, which is helpful but not a direct comparison with 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?

With no annotations and no output schema, the description carries the full burden of behavioral disclosure. It signals an asynchronous generation ('Start a preview generation') but does not explain side effects, job status, required permissions, or how the result 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?

The description is a single front-loaded sentence with no filler. Every word contributes, naming the action, resource, and scope of course types.

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

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

For a tool that starts a generation job with three parameters, no annotations, and no output schema, the description omits critical context: how to identify the course, when to provide universitySlug vs organizationSlug, and how to track the resulting job. Sibling tools like get_job_status and wait_for_job exist, but the description does not point to them.

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 for the three undocumented parameters. It only hints at course types (self-published, organization, university) without mapping them to slug, universitySlug, or organizationSlug, leaving ambiguity about which slug is required for each 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 uses a specific verb and resource ('Start a preview generation for a course') and clarifies it covers self-published, organization, or university courses, which distinguishes it from sibling tools like preview_book, preview_subset, and preview_single.

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 generating course previews and scopes the course types, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions 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 the disclosure burden. It discloses an important side-effect guarantee ('without touching Subset.txt') and the output filename, but it does not say whether the saved PDF overwrites existing files, whether it is temporary, or what permissions are needed.

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 the core action and scope front-loaded and no filler. The output filename detail earns its place.

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

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

For a two-parameter tool with no annotations and no output schema, the description is serviceable but thin. It gives enough to infer basic invocation, but the meaning of slug and the lifecycle of the generated PDF are left underspecified.

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 implies that 'markdown' is raw Markdown content and that 'slug' is used in the output filename, but it never defines what slug identifies or whether it must match an existing resource.

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 ('Preview') and resource ('a single chapter from raw Markdown content'), and distinguishes the tool from siblings by noting it does not touch Subset.txt. This clearly separates it from preview_book and preview_subset.

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

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

The description provides clear context for when to use the tool: previewing a single chapter from raw markdown while avoiding changes to Subset.txt. It does not explicitly name alternative tools or list when-not conditions, so it misses full routing guidance.

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

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

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It mentions that the preview is 'faster' and 'PDF-only', which is somewhat behavioral, but it does not mention whether this is a write operation, if it requires authorization, if it is destructive, or what side effects it has (e.g., does it create a file?). For a tool that could be nondeterministic, more detail is needed.

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

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

The description is a single sentence, which is concise and front-loaded with the core purpose. It includes a key qualifier ('PDF-only') and a hint about the mechanism ('using Subset.txt'). There is no extraneous information, so it is efficient, though it could be slightly more informative without losing 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?

The tool has a single parameter and no output schema, so the description is the only source of context. Given the presence of sibling preview tools (preview_book, preview_single, preview_course), the description should explain what 'subset' means, how it differs from full previews, and what the output will be. It lacks these details, making it incomplete for an agent to use correctly without additional assumptions.

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 one parameter, 'slug', with no description and 0% coverage. The description does not explain what 'slug' means in this context (e.g., is it a book slug, a course slug?) or what format it should be in. The description references 'Subset.txt' but does not link it to the parameter. The agent must infer that 'slug' identifies the subset, which is a significant gap given the lack of 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 states a verb ('Generate') and a resource ('preview'), but the resource is vague—'preview' could refer to any of the sibling preview tools. It mentions 'PDF-only' and 'using Subset.txt', which adds specificity, but it does not clearly distinguish it from preview_book or preview_single. It is not a tautology, but the purpose could be clearer.

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 hint about when to use it: 'faster PDF-only preview' and 'using Subset.txt', implying it is for a quick subset preview, but it does not explicitly state when to choose this over preview_book or preview_single, nor when not to use it. There is no mention of alternatives or exclusions, so an agent might not know the differentiator.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the primary effect but omits side effects like email notifications (the emailReaders parameter exists but is not referenced), irreversibility, or failure modes. For a mutation tool, this is under-disclosed and potentially misleading about consequences.

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, grammatically complete sentence with zero superfluous words. The action and object are front-loaded, making it easy to scan. However, the brevity comes at the cost of essential details noted in other dimensions.

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

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

For a mutation tool with three parameters and no output schema, the description lacks critical context: return values, side effects, required prerequisites, or error conditions. It does not explain what 'latest version' means or whether publishing is reversible, leaving the agent with insufficient information to use it reliably.

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

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

Schema description coverage is only 33% (only emailReaders is documented). The description does not explain the required 'slug' or the optional 'releaseNotes' parameter, nor does it clarify how they affect publishing. It adds little meaning beyond the field names already present 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?

The description clearly states the action (publish) and resource (book) with an explicit effect: 'making the latest version available to readers.' This distinguishes it from siblings like unpublish_book, preview_book, and publish_course without 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?

No guidance is given on when to use this tool versus alternatives such as unpublish_book, retire_book, or close_book. It does not mention prerequisites (e.g., a draft already existing) or conditions that should trigger publishing, leaving the agent to infer usage from the name alone.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states the operation and publication modes but does not explain what publishing actually changes, whether it makes the course publicly visible, whether it is reversible, or whether it has side effects on existing published versions. This is minimal behavioral context for a state-changing tool.

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

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

The description is a single concise sentence with the verb and resource front-loaded. It contains no filler or redundant phrasing. However, the brevity trades off necessary semantic detail, so it is concise but not fully effective.

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?

This is a state-changing operation with six parameters, no annotations, and no output schema, yet the description provides only a one-line purpose. It leaves critical invocation details undefined, including how to choose between self-published, organization, and university modes, and what the required slug refers to. An agent could identify the tool but not reliably call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate, but it only hints at two of the six parameters through 'organization' and 'university'. The required 'slug', along with emailReaders, releaseNotes, and percentComplete, are completely unexplained in both schema and description. This is insufficient for an agent to understand how to fill the parameters correctly.

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 and resource: 'Publish a course', and adds scope by naming three publication modes (self-published, organization, university). It is distinguishable from create_course and preview_course by the publish action, but it does not explicitly name or contrast any sibling, so it falls just short of full 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?

There is no guidance on when to use this tool versus create_course, preview_course, publish_book, or unpublish_book. No workflow prerequisites are mentioned, such as whether the course must already exist or be in draft state, and no exclusions are provided. The only implied usage is the action itself.

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

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

No annotations are provided, so the description carries the burden of behavior. It states the core action and future notification effect, but does not disclose side effects, confirmation behavior, duplicate handling, or whether data is shared with the author. No contradiction with annotations exists because there are 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?

A single well-formed sentence that front-loads the action and purpose without any filler or repetition.

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

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

With no annotations, no output schema, and no parameter descriptions, an agent is left guessing about return values, error cases, and the role of shareEmailWithAuthor. The description is not complete enough for fully confident 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 does not explain the parameters. It only hints that 'reader' maps to name/email and 'unpublished book' maps to slug, but it does not clarify the optional shareEmailWithAuthor parameter or required input formats.

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?

Uses a specific verb ('register') with a clear object ('a reader's interest in an unpublished book') and outcome ('notified on publish'). It is distinct from sibling tools like publish_book and get_interested_readers.

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

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

The description clearly implies when to use it: for unpublished books that need reader interest captured. It does not explicitly name alternatives or exclusions, but the 'unpublished' qualifier and sibling context make the intended use reasonably 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?

With no annotations, the description carries the full burden and does well: it discloses that purchases are stopped, existing reader access is preserved, and there is an authorization restriction (primary author only). It does not mention reversibility or return behavior, but the core behavioral traits are clearly stated.

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 tightly packed sentence with no filler. The main action, key behavioral outcomes, and an access restriction are all front-loaded and each phrase 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 single-parameter tool with no annotations, the description covers the prerequisite (published), the access restriction (primary author), and the operational outcome (no new purchases, existing access retained). It does not describe the return value, but that is a minor gap for this simple mutation tool.

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

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

Schema description coverage is 0%, so the description should compensate for the undocumented 'slug' parameter. It does not explain that slug identifies the book to retire, nor how to obtain it. The single parameter is conventional, but the description adds no semantic value beyond the bare property name.

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

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

The description uses a specific verb ('Retire') and resource ('a published book'), and states the defining effect: no new purchases while existing readers keep access. This distinguishes it from related lifecycle tools like unpublish_book or close_book without needing to open the schema.

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

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

The description gives clear context for when the tool applies: the book must be published, and only the primary author can perform the action. It does not explicitly name alternatives or state when-not-to-use, but the published-book condition and access implications make the usage context reasonably 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?

No annotations are provided, so the description must carry the full behavioral burden. It only restates the core action and authorization; it does not explain what unpublishing does to the book's visibility, whether it is reversible, or what other side effects occur.

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 key authorization note is compactly parenthesized. It is front-loaded and every word 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 mutation tool with no annotations and no output schema, the description is too sparse: it leaves the behavioral effect of unpublishing, the meaning of slug, and the expected response unresolved. An agent can identify the target action but would still be guessing at important operational details.

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

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

The schema provides only the slug's type and requiredness, with zero parameter descriptions. The description does not explicitly say the slug identifies the book or describe its format, leaving the agent to infer the parameter's meaning from 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 clearly names the action ('Unpublish') and the resource ('a book'), and adds an authorization constraint ('primary author only'). It does not explicitly contrast with lifecycle siblings like retire_book or close_book, 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 parenthetical supplies a useful usage restriction: only the primary author may unpublish. However, no guidance is given about when to choose unpublish_book versus related lifecycle tools such as publish_book, retire_book, or close_book.

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 discloses partial-update semantics and the types of changes supported (suspension, max uses), which is meaningful. However, it does not reveal side effects of suspending a coupon, required permissions, idempotency, or response behavior — important gaps for a mutation.

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 the action and resource front-loaded. 'Only include fields to change' delivers high-value usage guidance in minimal words. The trailing 'etc' is slightly loose but not wasteful.

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

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

No output schema and no annotations, so the description must be complete enough for safe invocation. It provides update behavior and examples, but omits identifier semantics (slug vs. couponCode), return values, and any caution about destructive consequences such as suspending a coupon. For a mutating tool with no annotation backing, this is insufficient.

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 for the six parameters. It explains suspended and maxUses through examples and implies other fields are changeable, but it does not clarify the distinct roles of slug vs. couponCode or the meaning of note/endDate. Partial compensation only.

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 ('Update') and resource ('existing coupon'), with concrete examples of operations (suspend/resume, change uses). It distinguishes itself from creation/retrieval siblings by emphasizing 'existing' and partial updates, though it doesn't name sibling 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?

Implies this tool is for modifying existing coupons and adds a clear usage directive: 'Only include fields to change' — a valuable instruction about how to structure the call. It does not explicitly mention alternatives or exclusion conditions, leaving when-to-use vs. other coupon tools to inference.

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

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

With no annotations, the description carries the transparency burden. It conveys that the tool performs a verification action and returns a user, but it does not disclose edge-case behavior such as error handling on an invalid key, whether any external network call occurs, or that the operation is read-only.

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

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

A single, front-loaded sentence that states the verb, object, and result with no filler. Every word 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 parameterless tool, this is nearly complete: an agent knows exactly what action to take and what result to expect ('authenticated user'). It could be strengthened by describing the shape of the returned user object, but that is a minor gap given the tool's simplicity.

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

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

The tool has zero parameters, so the schema needs no parameter documentation. The description adds the useful context that the key being verified is the 'configured' Leanpub API key, which is the only input-relevant detail. Baseline for zero params is 4.

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

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

The description uses the specific verb 'Verify' with the object 'configured Leanpub API key' and states the outcome 'return the authenticated user.' This is immediately distinguishable from all sibling tools, which concern books, coupons, courses, and royalties.

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 intended use is implied: call this when the API key needs checking and the current authenticated user is needed. However, the description does not explicitly say when to prefer this tool or that it should be used as a preflight auth check, and it names no alternatives or exclusions among the 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?

With no annotations provided, the description must carry the full behavioral burden. It discloses the polling loop, the configurable interval, and the timeout condition, which are core behaviors. However, it does not clarify whether the tool is read-only, what happens on timeout (error vs. last status), or that it may issue many HTTP requests. It stops short of full transparency.

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

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

Two sentences, front-loaded with the action, and every word earns its place. No filler, no repetition of schema details, and the usage hint is efficient. Perfectly concise for the tool's simplicity.

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 polling trigger and duration, but not the return value (what the tool ultimately gives the agent) or failure semantics on timeout. It also assumes the agent knows that 'slug' refers to the job identifier produced by preview_book/publish_book, which is only implied by 'right after.' For a 3-parameter tool with no output schema, these gaps are noticeable.

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%, with slug undocumented and timeoutSeconds/intervalSeconds having descriptions. The description adds meaning by linking 'every 5s (configurable)' to intervalSeconds and 'timeout elapses' to timeoutSeconds, reinforcing schema info. It doesn't explain slug's purpose, but the timing context is somewhat enriched. This is adequate but not exceptional given the schema already covers most 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 uses a specific verb ('poll') and resource ('get_job_status') and clearly describes the looping behavior until completion or timeout. It distinguishes itself from the single-shot get_job_status sibling by framing this as the waiting/polling wrapper, and it even names the trigger context ('right after preview_book/publish_book').

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 states when to use the tool: 'Use right after preview_book/publish_book.' This gives clear context and differentiates it from a standalone status check. It doesn't list exclusions or alternative scenarios, but the primary use case is well directed.

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