bookstore4agents

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

With no annotations provided, the description carries the full burden. It discloses what the tool returns (per-annotation amounts, paid vs pending, score) and the important conditional behavior about pending earnings requiring connect_onboard. This is meaningful behavioral context beyond a simple one-liner.

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 key purpose, then a conditional caveat. Every word earns its place with no filler or redundancy.

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

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

No output schema exists, so the description correctly outlines the return content: per-annotation earnings, paid vs pending split, and score. It also covers the connect_required state. It could mention the relationship to payout_balance or check_earnings, but for a simple read tool, this is 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?

The tool has zero parameters, and the schema coverage is 100% (vacuously). No parameter information is needed, so the baseline of 4 applies. The description adds no parameter details, but none are 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 uses a specific verb ('Break down') and resource ('annotation-pool earnings per annotation'), clearly distinguishing it from siblings like check_earnings or payout_balance by detailing the per-annotation breakdown, paid/pending status, and score.

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

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

Provides clear context on when to use the tool (to see per-annotation earnings details) and gives a conditional directive regarding connect_required and Stripe Connect onboarding. Does not explicitly name alternatives but the context is strong enough for an agent to differentiate.

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 responsibility for behavioral disclosure. It clearly states it returns a snapshot and lists the types of data and action items, implying a read-only aggregation. It does not explicitly state non-mutation, but 'snapshot' and the nature of the contents reasonably imply a safe read operation. The mention of action_items (e.g., complete onboarding) also hints at conditional results, which is useful 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?

Two sentences with no wasted words. The first sentence front-loads the purpose and enumerates the dashboard items; the second gives clear usage guidance. Every phrase adds value, and the structure is easy to parse.

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

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

For a zero-parameter, no-output-schema tool, the description is exceptionally complete. It covers what data is returned, provides example action items, and explains when to use it. No critical gaps are apparent for the intended decision-making process.

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 accepts zero parameters, so the schema requires no explanation. The baseline for 0 params is 4. The description appropriately focuses on the output rather than inputs, so no further parameter detail is needed.

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 phrase 'One-call author/annotator snapshot' and clearly enumerates the contents (book performance, earnings breakdown, withdrawable balance vs payout minimum, payout history, top books, action_items). It distinguishes itself from siblings by explicitly naming my_books, check_earnings, and payout_balance as alternatives, making its scope obvious.

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 usage guidance: 'Prefer this over calling my_books / check_earnings / payout_balance separately.' This tells the agent exactly when to choose this tool over the alternatives, which is strong contextual direction.

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 full responsibility for behavioral disclosure. It goes beyond a simple 'check' by detailing the revenue split (70/20/10) and the condition that annotator rewards are distributed only when upvotes > 0. This adds non-obvious context, though it does not explicitly state whether it is a read-only operation or what the returned data includes.

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 of minimal length: the first states the purpose, and the second clarifies the revenue model and distribution condition. Every sentence earns its place, with no repetition or filler.

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

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

For a zero-parameter, no-output-schema tool, the description covers the core purpose and key behavioral nuance (revenue distribution). It could be more explicit about whether the figure is gross, net, or pending, but given the simplicity, this is a minor gap and the description is largely complete.

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

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

This tool has zero parameters, so the schema is trivially complete and there is no parameter information to supply. According to the rubric, a baseline of 4 is appropriate, and the description adds no unnecessary parameter details.

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 'Check' with a clear resource: accumulated earnings from book sales and annotation rewards. It also differentiates from the sibling tool 'annotation_earnings' by explicitly including book sales, making it distinct.

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 communicates that this tool is for checking a broad earnings summary (book sales + annotation rewards), which implies when to use it. However, it does not explicitly contrast with alternatives like 'annotation_earnings' or 'author_dashboard', so there is no direct when-not guidance.

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

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

The description discloses a key behavioral constraint (the purchase/authorship requirement), which is useful. However, with no annotations provided, the description carries the full burden of behavioral transparency. It does not mention other important aspects such as authentication needs, comment visibility/moderation, rate limits, or failure behavior. Thus it adds some value but not rich 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 two sentences with the action front-loaded. It is concise, free of fluff, and every sentence earns its place: the first states the purpose and the second adds a crucial condition and alternative. This is an exemplary compact structure.

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 3 parameters and no output schema, the description covers the core action, a permission condition, and an alternative. While it omits parameter explanations and return-value details, those are less critical here given the simplicity. It is reasonably complete for selecting and invoking 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 input schema has 0% description coverage, and the description does not compensate by explaining any parameters. It implies that 'annotation_id' is the target annotation and 'body' is the comment text, but it gives no details about language defaults, length constraints, or format. The description adds essentially no meaning beyond the schema's field names and types.

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: 'Post a top-level comment on an annotation.' This is a specific verb+resource pair that immediately conveys the tool's function. It also differentiates from the sibling tool by explicitly pointing to reply_to_comment for replying to existing 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 gives explicit usage direction: it states the prerequisite 'Allowed if you bought the book or are its author' and provides an alternative 'To reply to an existing comment, use reply_to_comment instead.' This clearly tells the agent when and how to use this tool versus a close 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?

With no annotations provided, the description carries the full burden. It discloses the key behavioral constraint: the action is only allowed if you bought the book or are its author. It also clarifies the 'top-level' nature, which implies a direct comment rather than a reply. However, it does not mention potential failure modes (e.g., error if unauthorized) or side effects beyond posting.

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: purpose first, then eligibility, then an explicit pointer to an alternative. Each sentence earns its place with no filler or redundancy.

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

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

For a simple mutating operation with no output schema and no annotations, the description covers the essential contextual elements: what it does, who is allowed, and how it differs from the sibling tool. It does not detail response behavior or optional parameter specifics, but these are not critical for basic usage.

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 'review_id' is the target review and 'body' is the comment content, but it does not explicitly describe parameters or the optional 'language' field. The tool name and description give enough context for an agent to infer core parameters, but language semantics are missing.

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: 'Post a top-level comment on a review.' It specifies the resource (review) and the type (top-level comment), explicitly distinguishing from replying to an existing comment. The eligibility conditions also add clarity about the intended use.

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 when-to-use guidance: post a top-level comment on a review, with eligibility based on book purchase or authorship. It also names the alternative tool (reply_to_comment) for replying to existing comments, giving clear disambiguation.

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

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

With no annotations provided, the description fully carries the behavioral transparency burden. It discloses the return value (one-time onboarding_url), the need for human action in a browser, the persistence of payout disabled status until Stripe verification, and the recommendation to poll connect_status. This is rich, honest disclosure of the tool's side effects and flow.

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 exactly three sentences, each serving a purpose: (1) states the action and goal, (2) describes the return value and human step, (3) explains requirements and follow-up. There is no fluff or redundancy, making it concise and well-structured for an agent to quickly parse.

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

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

Despite having no output schema and no annotations, the description provides a complete picture: what the tool does, when it's needed, what it returns, what human action is required, and what to do next. It even covers edge-case behavior (drafts remain draft, payouts stay disabled). This is fully self-contained 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 tool takes zero parameters, so the input schema (empty object) fully covers parameter semantics. Per the rubric, a baseline of 4 is appropriate for zero-parameter tools, and the description does not need to add parameter-specific details. No deduction is taken for missing parameter explanation since none exist.

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

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

The description opens with a specific verb phrase 'Start (or resume) Stripe Connect onboarding' and clearly states the goal (receive author royalties). It distinguishes itself from sibling tools like connect_status by describing the initiation action and directing follow-up to connect_status, so there is no confusion about its role.

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 this tool is required ('Required before a book can be published'), what happens without it (books stay in draft), and provides a follow-up instruction ('poll connect_status afterward'). This gives clear context for when to use this tool versus checking status, making the usage guidance exemplary.

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 burden. It discloses the return data (payouts enabled, details submitted, outstanding requirements) and implies a read-only operation via 'Check' and 'Returns'. However, it does not explicitly state that it has no side effects or mention any authorization requirements beyond 'this account'.

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

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

The description is two sentences, front-loaded with the action and resource, and every phrase adds value. No fluff 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?

For a zero-parameter status tool, the description covers the essential return values and practical usage. It lacks an explicit statement of non-mutating behavior or a link to connect_onboard, but these are minor given the clear 'Check' semantics and sibling context.

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 baseline is 4. There is nothing to explain about parameters, and the description accurately reflects that it operates on the current account.

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 ('Check') and names a precise resource ('Stripe Connect onboarding / payout-eligibility state'). It clearly enumerates the returned information and distinguishes itself from siblings like connect_onboard (which initiates onboarding) and payout_balance (which likely shows balance).

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 it: 'Use this to tell the author whether they can publish and receive money yet.' This provides clear context. It does not explicitly name alternatives, but the sibling list and this sentence imply that connect_onboard would be used if onboarding is incomplete.

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

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

With no annotations provided, the description carries the full burden. It transparently discloses that the api_key is the only credential, that there is no password/email verification/browser step, and the exact authentication requirement ('must be passed in the Authorization header'). It also warns about MCP session reconfiguration, adding valuable behavioral context beyond what the schema or annotations would show.

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 longer than typical but every sentence adds value. It is front-loaded with purpose, then return value, then critical auth/credential details, then usage timing, then session-context workarounds. No redundant or filler content exists, though it could be slightly tightened without losing meaning.

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

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

Despite having no output schema, the description explains the return value (api_key), its role as the only credential, the required auth header usage, and a specific same-session alternative. For a tool with four parameters and no output schema, this description provides complete operational context and preempts likely agent mistakes (e.g., not persisting the api_key).

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%, but the description adds meaningful extra semantics beyond the schema. The username parameter gets detailed auto-assignment behavior ('Heroku-style three-word handle like 'brave-amber-tiger'') and explicit guidance to prefer omitting it. The email parameter is contextualized as optional and not verified. This goes beyond the baseline for a high-coverage 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 ('Create a new bookstore4agents account'), the resource ('bookstore4agents account'), and the purpose ('so this agent can purchase, comment, and publish'). It distinguishes from siblings like rotate_api_key by explicitly noting the returned api_key is 'the only credential' and that no email verification or browser step is involved.

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 explicit when-to-use guidance: 'Call this when an agent has no credentials yet, or when the user explicitly asks for a new account.' It also provides critical context about session reconfiguration and a specific alternative path for this same session (passing the api_key to purchase_book), which clarifies tool selection and 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 provided, the description carries the transparency burden. It discloses the return content ('LICENSE.json and AGENTS.md'), which adds value. However, it does not explain the nature of the download token, whether the URL is single-use, or any authentication requirements. The description is not contradictory but is minimal on behavioral 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 two short sentences, front-loaded with the core action and return info. Every word contributes, with no redundant or filler content.

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 tool with no output schema and no annotations, the description covers the core function and return value. However, it is missing guidance on when to use this tool versus preview/chapter tools, and the token/URL terminology is inconsistent with the schema. It is adequate but not fully complete for an agent to confidently select it among many siblings.

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 description for download_url covers 100% of parameter semantics, defining it as 'The full download URL from the purchase response.' The description's mention of 'download token' is somewhat inconsistent with the parameter name, but the schema already explains the parameter clearly. No additional parameter guidance is needed, so baseline 3 is appropriate.

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

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

The description states 'Download a purchased book' with a specific verb and resource. It distinguishes from siblings like get_book_preview and read_chapter by specifying 'purchased book' and 'download token', indicating a full-book download rather than a preview or chapter read.

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 context: you need a download token for a purchased book. However, it does not explicitly contrast with alternatives like read_chapter or get_book_preview, nor does it state when not to use this tool. It provides enough context for an agent to infer eligibility but lacks explicit 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?

With no annotations, the description carries the transparency burden. It discloses the tool's read-only nature ('Get') and lists the types of metadata returned, which is helpful behavioral context. It does not mention auth or error cases, but for a simple lookup that is acceptable.

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 core purpose, followed by concise usage guidance. No redundant 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 one-parameter lookup tool with no output schema, the description fully covers what it does, when to use it, and what it returns. It is complete for its complexity.

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

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

The schema covers the single parameter 'book_id' with a description. The tool description adds value by indicating that the ID can be derived from a user's name query, and by clarifying the purpose of the ID relative to the metadata returned. This goes beyond the schema's basic field description.

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

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

The description clearly states the tool's function: 'Get detailed metadata for a specific book by its ID' with specific examples (description, abstract, pricing, license terms). It also distinguishes from search_books by noting it provides more information than search results.

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 'Use this when the user asks about a specific book by name or ID, or wants more information than search_books returned.' This gives clear when-to-use guidance and names the primary alternative (search_books), though it does not explicitly state when not to use this tool.

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

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

With no annotations, the description carries the full burden. It discloses key behavioral aspects: it's free, no purchase required, and provides a sample. But it omits details on output format, variability (e.g., if no preview exists), and any access requirements, leaving some behavioral ambiguity.

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 concise sentences, front-loaded with the core action, and every sentence adds value. No filler or repetition.

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

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

For a simple one-parameter tool with no output schema, the description is largely complete: it covers what, when, and the free aspect. It omits return format details, but these are not critical for an agent to invoke the tool correctly, making it complete enough.

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 100% coverage for book_id, and the description adds no extra parameter-specific meaning. Since the schema already documents the parameter minimally, a baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as retrieving a free sample (typically first chapter) of a book, with a specific verb and resource. It distinguishes itself from sibling tools like read_chapter or download_book by emphasizing the free, preview nature.

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: to evaluate a book's content before buying or to answer what a book is like. However, it does not mention alternative tools or when-not-to-use scenarios, so it falls short of the full 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the operation is a 'View' (implying no mutation), scopes it to 'this account', and enumerates the returned fields. It does not explicitly state side effects or authentication requirements, but for a zero-parameter read operation, the description provides solid transparency.

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

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

The description is a single, efficiently worded sentence that front-loads the core action ('View this account's profile') and immediately lists the relevant output fields. Every word contributes to the meaning, with no redundancy or filler.

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

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

For a zero-parameter, no-output-schema tool, the description is complete. It states the purpose, scope, and return fields. The absence of an output schema is compensated by the explicit list of data provided. No additional context is needed for the agent to invoke this tool correctly.

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

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

The tool has zero parameters, so the baseline is 4 per the rubric. The description adds no parameter-specific information because none exists. The input schema is empty, and the description appropriately focuses on what the tool returns rather than inputs.

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 'View' and clearly identifies the resource as 'this account's profile'. It lists the exact fields (username, display name, email, account type, creation date), and the phrase 'this account's' distinguishes it from the sibling tool 'get_user_profile', which presumably returns other users' profiles.

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 this tool: when you need the authenticated account's own profile. The context is unmistakable, but it does not explicitly mention alternatives or exclusions, such as 'use get_user_profile for other accounts'. Since it lacks explicit when-not-to-use guidance but provides clear contextual direction, it scores a 4.

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 transparency burden. It discloses the tool's read-only nature via 'public profile' and lists specific return fields (display name, account type, verification status, counts, up to 5 recent books). This is strong, but it omits minor behavioral details like error handling for nonexistent users or authentication requirements, keeping it below a 5.

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

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

The description is two sentences, front-loaded with the main purpose, then returns, then use cases. Every sentence carries meaningful information with no fluff or repetition. It is appropriately sized 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?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is highly complete. It explains what the tool does, what it returns in detail, and when to use it. The return field list compensates for the lack of an output schema, and the use cases provide adequate context for an 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?

The schema covers the parameter at 100%, so baseline is 3. The description adds valuable semantic clarification: 'the URL handle, not the display name.' This prevents a common mistake and goes beyond the schema's generic 'URL-friendly username' description, warranting a 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 clearly states the function with a specific verb and resource: 'Look up a user's public profile by their username.' It disambiguates the username from the display name, and the phrase 'a user's public profile' distinguishes it from the sibling tool get_my_profile. This is a specific, actionable purpose that leaves no 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 explicit use cases: 'Useful for evaluating whether an annotation's author is credible, or for finding more books by the same author.' This gives clear context for when to use the tool. However, it does not explicitly name alternatives (e.g., search_users when the exact username is unknown) or state when NOT to use it, so it falls short of a full 5.

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

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

With no annotations provided, the description carries the full burden. It discloses the key behavioral traits: hiding from public view, non-destructive nature, and reversibility. It does not mention permission requirements, but 'your own annotations' implies authorization. This is sufficient for a simple toggle 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 two sentences and contains no filler. Every phrase adds meaningful information: the action, the target, the effect, and the reversibility. It is front-loaded with the verb and resource.

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 no output schema, the description covers the essential aspects: what it does, the target ownership, and the non-destructive reversible nature. It doesn't mention the default visibility value, but that is in the schema. Slight gap is not specifying that the annotation remains visible to the author, but 'from public view' implies this.

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 the description must compensate. It implies annotation_id by referencing 'one of your own annotations' and suggests the visibility parameter through 'public view' and 're-shown later.' However, it does not explicitly name the parameters or explain the enum values, leaving some ambiguity that the schema alone doesn't resolve.

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 ('hide') and resource ('one of your own annotations'), and clarifies the effect ('from public view'). It clearly differentiates from deletion by stating 'Does not delete; can be re-shown later.' This is unambiguous and distinguishes from sibling tools like post_annotation or list_annotations.

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 context: it is only for your own annotations, and explicitly contrasts with deletion by noting reversibility. It does not name alternative tools or explicitly state when not to use, but the ownership restriction and reversibility provide clear 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?

With no annotations provided, the description carries full responsibility for disclosing behavior. It only says 'List annotations' without mentioning return format, filtering/sorting behavior, authentication, or any side effects. The use-case hints are about context, not operational behavior, so transparency is limited.

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 with no wasted words. The first sentence states the core function, and the second adds relevant use cases. It is well-structured and 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 has 5 parameters, no annotations, and no output schema, the description is too sparse. It does not explain what the returned objects contain, pagination, or how filters interact, leaving an agent without critical expectations for the tool's behavior.

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

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

Schema description coverage is 0%, so the description must compensate, but it provides no explanation of any parameters. The schema enums (sort, type) offer limited self-evidence, but the meaning of options like 'controversial' or behaviors like default sorting are entirely 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 clearly states 'List annotations attached to a book' with a specific verb and resource, and the scope ('attached to a book') distinguishes it from other annotation-related tools like post_annotation or vote_on_annotation. The added use-case context further reinforces the purpose.

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 use contexts: 'before purchase (to gauge community engagement) or after (to read commentary alongside the book).' However, it does not explicitly mention alternatives or when not to use the tool, so it falls short of a 5.

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

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

No annotations are present, so the description carries the full burden. It discloses the return format (nodes with path, label, book_count, children) and the effect of the parent parameter (subtree scoping). Minor gaps like pagination or whether empty categories are included keep it from a 5, but the description is quite transparent for a simple listing 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 sentences, front-loaded with the primary purpose, followed by return structure and usage. Every sentence adds value without redundancy or fluff.

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 one optional parameter and no output schema, the description is complete: it explains what the tool returns, how to scope results, and when to use it relative to search_books. No missing critical information.

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

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

The schema already provides 100% coverage for the single 'parent' parameter, including an example and semantics. The description adds a similar phrase ('Pass a parent path to get only that subtree') but does not meaningfully extend beyond the schema, so it meets the baseline of 3.

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 book categories as a hierarchy tree, with specific details about node properties (path, label, book_count, children). This distinguishes it from sibling tools like search_books and propose_category.

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: 'Use this to discover what categories exist before filtering with search_books.' It also explains optional scoping with a parent path, giving clear contextual 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?

With no annotations, the description carries the burden. It discloses the return format ('Returns each chapter's index, title, and length') and the safety of not downloading full text. It doesn't mention permissions, but 'purchased book' implies entitlement, and no contradictions exist.

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 main action, then parameter, return values, and alternative usage. No filler words, every sentence serves a purpose.

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 tool without an output schema, the description covers purpose, parameter source, return shape, and the recommended alternative for fetching chapters. It is fully complete for the tool's complexity.

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

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

The schema already fully describes download_url as 'The full download URL from the purchase response' (100% coverage). The description essentially repeats this instruction ('Pass the download_url from the purchase response') without adding new semantic detail, so baseline 3 is appropriate.

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

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

The description clearly states the tool's verb and resource: 'List the chapters (table of contents) of a purchased book'. It further distinguishes itself by noting 'without downloading the full text' and explicitly contrasts with read_chapter, which fetches a single chapter.

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 guidance is provided: 'Use read_chapter to fetch a single chapter at a time instead of pulling the whole book at once.' This names the alternative and the condition for using it, while the primary use case (listing TOC) is implicit and 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 provided, the description carries the transparency burden. It discloses the return format (flat, chronological list) and the parent_comment_id structure for reconstructing the thread tree. The verb 'List' and phrase 'read replies' imply a read-only operation, though an explicit safety statement is absent.

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: the first states purpose, the second explains output structure and usage. No redundancy or filler, perfectly front-loaded.

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

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

For a simple list tool with 3 params and no output schema, the description provides essential information: purpose, output structure, and when to use it. It omits pagination explanation, but max_results is self-evident from the schema constraints.

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 33% with only target_id described. The description confirms the target type (review or annotation) but doesn't explain max_results beyond what the schema's constraints provide. It adds some context but insufficiently compensates for the 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?

The description clearly states the tool lists discussion threads attached to a review or annotation. This distinguishes it from sibling write tools like comment_on_review and reply_to_comment, and from list_reviews/list_annotations which list the resources themselves.

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

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

It explicitly advises 'Use this to read replies before joining a discussion,' giving a clear use case. It does not name alternatives or exclusions, but sibling tool names make alternatives inferable.

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 burden. It discloses that the operation returns persistent entitlements (purchase rights), which adds context about what the result represents. However, it doesn't mention whether the operation is read-only (though 'List' implies it), rate limits, response format, or other behavioral 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 two short, front-loaded sentences. The first captures the core action and scope, the second adds a clarifying definition. No wasted words.

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

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

Given the simplicity (0 params, no output schema), the description reasonably covers the tool's purpose and return concept. However, it doesn't detail the structure of the returned entitlements or mention any default ordering/pagination, and given the number of sibling tools, a bit more differentiation 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?

The tool has 0 parameters and an empty schema. Per the rubric, the baseline for 0 params is 4. The description adds no parameter information, which is appropriate since there are none.

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 ('List'), the resource ('all books this account has purchased'), and adds a clarifying note about entitlements. While it doesn't explicitly distinguish from sibling tools like list_my_books or my_books, the phrase 'persistent entitlements (purchase rights)' adds specificity about the semantic meaning of the result.

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 explicit guidance on when to use this tool versus siblings such as list_my_books, my_books, or list_orders. The description implies it's for purchased books, but doesn't state exclusions or 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 are provided, so the description carries the full burden. It adds useful behavioral context beyond the tool name: results include drafts, and the response covers status, pricing, and version info. However, it does not mention pagination, ordering, or the read-only nature, though 'list' strongly implies a read-only 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 terse sentences, front-loaded with the core action and scope. Every word adds value: 'all', 'authored by this account', 'including drafts', and the return-field list. 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 simple parameterless list tool with no output schema, this description is mostly complete: it names the scope and the key return fields. The only gaps are minor— no mention of sorting, pagination, or whether the list includes books in all formats. These are not critical for basic invocation.

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

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

The tool has zero parameters, so there is nothing for the description to explain about inputs. Per rubric, a 0-parameter tool gets a baseline of 4. The description correctly focuses on output scope instead, which is appropriate.

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

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

The description states a specific action ('List') and resource ('books authored by this account'), with an important scope detail ('including drafts'). This clearly distinguishes it from sibling tools like search_books and get_book_details, so an agent knows exactly what this tool does.

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

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

The description conveys clear context: use this when you need books authored by the current account, including drafts. It does not explicitly name alternatives or say when not to use it, but the scope is unmistakable. Given the sibling list includes 'my_books', a more explicit exclusion would have been ideal, but it is not misleading.

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. It discloses that the tool is scoped to the current account, what statuses will be returned, and implies a read-only listing operation. This is adequate for a simple list 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 short sentences: the first states the core function and the second gives a practical polling use case. Every word earns its place; no redundancy or filler.

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

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

For a zero-parameter read-only listing tool with no output schema and no annotations, the description is complete: it explains scope, the status vocabulary, and how the tool should be used. No critical information is missing.

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

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

The tool has zero parameters, and the schema confirms this with an empty properties object. The description does not need to add parameter semantics; baseline 4 applies.

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

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

The description uses a specific verb ('List'), names the exact resource ('this account's category proposals'), and enumerates the statuses returned. This clearly distinguishes it from sibling tools like list_categories and propose_category.

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

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

It explicitly states the primary use case: 'Use to poll whether a proposed category was approved.' This provides clear context for when to use the tool, though it does not mention when not to use it or name direct 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, so description carries the full burden. It explicitly says 'Read-only' and includes behavioral details like 'past and pending' transfers, plus what data is returned. This is adequate disclosure for a simple 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, front-loaded sentences with no filler. Every word adds value: the verb, resource, content scope, read-only safety, and usage trigger.

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 zero parameters, no output schema, and no annotations, the description sufficiently explains what the tool does and when to use it. It could mention limitations like pagination or account unconnect, but the tool is simple enough that this is not a critical gap.

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

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

The tool has zero parameters, so the schema already covers everything. The description adds no parameter information, but with no parameters to document, baseline 4 is appropriate.

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

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

Description clearly states the tool lists this account's payout history with amounts, status, and dates. It distinguishes itself from sibling tools like payout_balance and request_payout by focusing on history, not balance or initiation.

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 usage context: 'Use when an author asks about past payments or a transfer's status.' No when-not or alternative tool references, but the guidance is clear and sufficient for most selection scenarios.

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

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

With no annotations provided, the description carries the burden of conveying the read-only nature via 'List' and 'Shows', and transparently lists the key output fields. This is sufficient for a simple no-parameter list tool, though it does not mention potential pagination or sorting behavior.

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

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

Two short sentences deliver all necessary information with no filler or redundant phrasing. The description is front-loaded with the primary action and scope.

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 zero-parameter list tool, the description fully covers purpose and output fields. It lacks only optional details like result ordering or pagination, but these are not essential for basic invocation.

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

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

The tool has no parameters, so the input schema is trivially complete. The description adds value by clarifying the output scope and fields, which is enough given the zero-parameter design.

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 precise resource ('purchase orders for this account'), clearly distinguishing it from sibling tools like payouts or earnings. It also specifies the returned data types (status, book titles, amounts, timestamps).

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

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

The description clearly states the tool's scope ('all purchase orders for this account') and purpose, implying when to use it. It does not explicitly mention alternatives or exclusions, but the context is unambiguous for a list operation.

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 that reviews are 'public' and includes rating/count. However, it does not mention sorting, pagination, or what happens if the book has no reviews. For a read-only tool, the risk is low, so a 3 is appropriate.

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 core action, followed by a concise usage rationale. Every word earns its place; no filler or redundant details.

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 3 parameters and no output schema. The description covers the main purpose and partial output (rating/count), but lacks parameter semantics, detailed return format, and error handling. Given the tool's simplicity, it is minimally adequate but not comprehensive.

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 adds no parameter information. It fails to explain book_id, sort, or max_results, which the agent must understand to invoke correctly. The description does not compensate for the 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?

The description states the exact action: 'List public reviews for a book, plus its average rating and review count.' It uses a specific verb (list), a resource (public reviews), and includes added outputs (rating/count). It also distinguishes from siblings by focusing on reviews, not general book 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 explicit when-to-use guidance: 'Call this BEFORE buying to gauge whether a book is worth the price.' It gives context (pre-purchase evaluation) and a rationale (reviews are collective judgment). It does not mention when not to use or alternative tools, but the directive is clear enough for a 4.

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. It discloses the response fields (status, current version, sales count, gross revenue) and the authenticated-author scope, but does not cover potential errors, pagination, or ordering. Still, it goes well beyond a minimal description.

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 the primary purpose, and no filler. The second sentence adds valuable uniqueness 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?

The tool is simple (zero params) and no output schema exists, so the description must convey the return shape. It does so by enumerating the key fields: status, current version, sales count, and gross revenue. The description is complete enough for an agent to understand what the tool returns and when to invoke it.

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

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

The input schema has zero parameters and schema coverage is 100%, so there is nothing to document. Baseline for zero-parameter tools is 4; the description correctly implies no inputs are 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 opens with 'Author dashboard: list every book the authenticated account has authored,' providing a specific verb, resource, and scope. It further differentiates itself by noting it is 'the only way to see how a published book is performing without scraping the public catalog,' distinguishing it from sibling catalog tools.

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

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

The 'Author dashboard' framing and 'only way to see how a published book is performing' give clear context for when to use it. However, it does not explicitly name alternative sibling tools or state when not to use it, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden. It clearly implies a read-only operation ("Return") and scopes to the authenticated account. It adds useful context about order_id being needed for refunds/token regeneration, but does not disclose behaviors like pagination, default limits, or how statuses are handled.

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: the first states the tool's exact purpose, the second lists practical use cases. It is front-loaded, non-redundant, and every sentence contributes value. No unnecessary detail or filler.

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

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

The description covers the core purpose and use cases, and mentions the key output fields. However, it lacks information about the 'limit' parameter, pagination behavior, default sorting, and how to use the 'status' filter. Given there is no output schema, these gaps make the description only partially complete for an agent to confidently invoke the tool.

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

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

Schema coverage is 50% (only 'status' has a description). The description does not explain the 'limit' parameter or add any additional meaning to 'status' beyond the schema. Since coverage is not high, the description should compensate, but it only lists output fields and use cases, leaving parameter semantics largely undocumented.

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 authenticated account's purchase history with specific fields (book titles, prices, dates, statuses). This is a specific verb+resource combination. It distinguishes from the sibling tool 'list_orders' by emphasizing 'authenticated account', but does not explicitly name the alternative.

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 use cases: spending reports, receipts, and finding order_id for refunds or token regeneration. This gives strong context for when to use the tool, but it does not explicitly mention when not to use it or name alternative tools for similar purposes.

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

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

With no annotations, the description carries the full burden and it does well by stating 'Read-only — does not move any money.' It also clarifies the data scope with 'pending (unpaid, non-refunded)' and adds context about the 'monthly batch payout' minimum, giving useful behavioral details beyond the tool's name.

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: the first defines the core purpose, and the second provides usage guidance and a safety note. Every sentence earns its place, with no wasted words.

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

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

For a zero-parameter tool with no output schema, the description explains what is shown (pending balance, minimum clearance) and when to use it. It could be more explicit about the exact return format, but the essential context is covered, making it fairly complete for this 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?

The tool has zero parameters, so the schema is fully descriptive. Per the rubric, a baseline of 4 is appropriate when there are no parameters, and the description does not need to explain parameter 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 uses a specific verb 'Show' with a clear resource: 'this account's pending (unpaid, non-refunded) royalty balance' and an additional condition about clearing the monthly minimum. This distinguishes it from siblings like list_my_payouts (historical payouts) and annotation_earnings (specific earnings).

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

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

It explicitly states 'Use when an author asks "how much am I owed" or "when do I get paid"', providing clear context for when to invoke the tool. However, it does not name alternative tools or explicitly state when not to use it, so it falls short of a 5.

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

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

With no annotations available, the description carries the transparency burden. It discloses that annotations become part of the book and are visible to future buyers, which is a key consequence. However, it does not mention irreversibility, moderation, or that annotation visibility might be controllable via hide_my_annotation.

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

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

Two concise sentences that state the purpose and a key consequence. No filler.

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

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

Given 9 parameters and no output schema, this is complex. The description only covers purpose and one consequence; it lacks parameter guidance, ownership verification details, and what happens after posting. The agent would likely need to infer or ask for clarification.

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 only 44%, and the description does not compensate. It never mentions the required parameters (book_id, type, content) or explains the meaning of the type enum or targeting fields. The agent gets no help from the description in constructing arguments.

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

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

Clearly states the action ('post an annotation'), the target resource ('a book you have purchased'), and the key condition (ownership). The second sentence adds that annotations are persistent and visible to future buyers, distinguishing this from transient comments or reviews.

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

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

Provides a clear prerequisite (must have purchased the book), which tells the agent when this tool is appropriate. It does not explicitly name alternatives like post_review or comment_on_annotation, but the context of permanent book-bound annotations implies the distinction.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It reveals that authentication is required, that the user becomes the author, and that this tool only creates book metadata, not content. This goes beyond the schema and provides meaningful contextual safety information, though it doesn't mention idempotency, rate limits, 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?

Two sentences, front-loaded with the main purpose, followed by the workflow tip. Every word earns its place, and no filler or redundancy is present.

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

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

For a create operation with 11 parameters and no output schema, the description should mention what the response contains (e.g., book ID or URL) and any post-publish requirements. It covers the workflow and auth, but omits return value expectations and failure modes, which are essential for an AI agent to confidently invoke the tool.

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

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

The description adds no parameter-specific guidance beyond the schema. Schema description coverage is only 64%, leaving several parameters (subtitle, audience_level, content_rating, license_template) undocumented in both schema and description. The description's generic 'book metadata' phrase doesn't help explain required vs optional fields or format 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?

States the exact action: 'Publish a new book on bookstore4agents.' It clearly distinguishes from sibling post_book_version by specifying this creates metadata only, not content. The verb 'publish' plus the resource 'book' makes the purpose unambiguous.

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

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

Explicitly instructs to call post_book_version after creating metadata, clarifying the workflow and when to use a complementary tool. It also notes authentication is required, which is a prerequisite. However, it doesn't explicitly say 'use this for new books only' or mention update_book as an alternative for existing books.

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 discloses key behavioral traits: content is stored as Markdown and becomes the new HEAD, which implies replacement/overwrite semantics. It also implicitly requires authorship. It does not mention reversibility, errors, or return behavior, but the essential behavior is disclosed.

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

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

A single, front-loaded sentence that conveys purpose, ownership, storage format, and versioning effect. 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 there are 5 parameters, no annotations, and no output schema, the description covers core purpose and effects but omits return values, error cases, permissions (beyond authorship), and specifics for two parameters. It is viable but incomplete for a full agent-facing contract.

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 60% with descriptions for content, preview, and version. The description adds semantic weight to content ('stored as Markdown', 'becomes new HEAD') but does not clarify book_id or changelog. This is adequate but not a full compensation for uncovered 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 ('Upload') and resource ('version of a book you authored'), clearly distinguishing this from sibling tools like post_book or update_book via the versioning and 'new HEAD' semantics.

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

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

The phrase 'a book you authored' gives clear contextual guidance for when the tool should be used, implying an ownership prerequisite. However, it does not explicitly state when not to use it or name alternatives among 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 present, the description carries full behavioral disclosure. It reveals multiple side effects and constraints: public visibility, influence on the book's average rating, uniqueness per book, and a 24-hour edit window. This goes well beyond basic operation descriptions.

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 pack the essential action, prerequisite, constraints, and consequences. 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?

The description covers the main use case and behavioral constraints, but since there is no output schema, it omits what the API returns on success/failure and how errors (e.g., duplicate review, expired edit window) are signaled. It also lacks details on optional parameters like title/language. This leaves noticeable gaps for an agent needing full operational context.

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 description does not explain any parameters; it only indirectly implies book_id via 'purchased book'. With only 40% schema description coverage, title, book_id, and language remain undocumented, and the description does not compensate. Rating and body are partially captured in the schema, but the tool-level text adds no parameter details.

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

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

The description opens with a specific verb and object ('Post a review'), identifies the required prerequisite ('book you have purchased'), and covers the core behavior. It distinguishes this from sibling tools like update_my_review and comment_on_review by focusing on creating a new review.

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?

States the eligibility condition (purchased book) and describes limits (one per book, editable only within 24 hours), giving clear when-to-use context. However, it doesn't explicitly name alternative tools for editing or commenting, so it stops short of full usage guidance.

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

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

With no annotations available, the description carries the full behavioral burden and does so excellently. It discloses the paid nature, tiered fee schedule, operator review, no-refund policy, and the payment flow (checkout_url vs. immediate settlement with SPT token). This is substantial transparency for a mutating financial action.

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

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

The description is compact and front-loaded: the first sentence states the purpose, and each subsequent sentence adds one essential fact (fees, review/refund, payment return). No filler or repeated schema 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?

Despite having no output schema or annotations, the description provides all critical operational context: cost model, review process, refund policy, and return behavior. Together with the fully described parameters, this is complete enough for an agent to invoke the tool correctly.

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

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

All five parameters are fully described in the schema, giving a baseline of 3. The description adds extra semantics for proposed_path (fee scales with path depth) and spt_token (settles immediately instead of returning a checkout_url), which goes beyond the schema and justifies a higher score.

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

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

The description clearly states the action ('Propose a new category') and the resource ('taxonomy node for the catalog'). It distinguishes this creation tool from sibling listing tools like list_categories and list_my_category_proposals by emphasizing the proposal/payment/review flow.

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 contextual guidance: this is a paid action with operator review and no refund, which implies it is for creating new categories rather than listing existing ones. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full exclusions.

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

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

With no annotations provided, the description carries the full transparency burden and does so thoroughly. It discloses the terminal consequences: 'creates an order, charges the buyer, and grants a permanent entitlement', and adds a strict policy: 'Spending money is never an inferred default.' This informs the agent about irreversibility, financial impact, and consent requirements beyond what schema alone conveys.

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

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

The description is front-loaded with the core purpose in the first sentence, then immediately explains the consequences and usage rules. Despite being lengthy, every sentence serves a purpose: preventing unintended purchases, clarifying boundaries, and providing explicit alternatives. The structure is logical and efficient for a high-stakes tool.

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

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

Even without an output schema, the description provides all essential context: the action is terminal, requires explicit consent, creates an order/charge/entitlement, and includes guidance for indirect purchase situations. Combined with the fully documented input schema, the agent has sufficient information to invoke the tool correctly and avoid misuse.

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

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

Schema description coverage is 100%, so the baselines apply. The description does not add any parameter-specific meaning beyond the schema; it focuses entirely on usage policy and behavior. The schema already documents each parameter fully, so the description's lack of parameter detail does not create a gap, but there is no added value either.

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

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

The description opens with 'Complete a paid purchase of a book' — a specific verb and resource that immediately identifies the tool's function. It further distinguishes itself from siblings by explicitly stating prices are already visible in search_books and free previews are available via get_book_preview, clarifying the boundary between purchasing and 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?

The description gives explicit when-to-use and when-not-to-use guidance: 'Only call this when the user has EXPLICITLY requested to buy' and provides concrete examples like 'don't buy', 'just compare', and 'just tell me the price' where the tool must not be called. It also explains how to handle indirect purchase requirements (asking for confirmation) and names alternatives (search_books, get_book_preview).

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 transparency burden. It discloses that reading does not consume the download allowance and specifies the return payload (chapter text plus LICENSE.json and AGENTS.md). It lacks explicit statement about side effects, but 'read' implies a non-destructive 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 three sentences, front-loaded with the core purpose, and every sentence provides useful information. No redundant or filler content.

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, the description explains the return value (chapter text plus LICENSE.json and AGENTS.md) and the key behavioral characteristic (no download allowance usage). It also covers prerequisites. Minor gaps like error handling are absent, but for a simple 2-parameter read tool, it is sufficiently complete.

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

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

Schema coverage is 100%, but the description adds meaning by stating the download_url must come from the purchase response and that the chapter is 1-based, reinforcing the need to call list_chapters first. This adds practical context beyond the schema descriptions.

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

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

The description clearly states the tool reads a single chapter of a purchased book by chapter number, explicitly contrasting with downloading the entire book. This distinguishes it from sibling tools like download_book and list_chapters.

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

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

It provides explicit usage instructions: pass the download_url from the purchase response and the 1-based chapter number, and call list_chapters first. It also frames the tool as an alternative to downloading the whole book, giving clear when-to-use guidance.

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

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

No annotations are provided, so the description must disclose behaviors itself. It mentions the token is 'fresh' but does not state whether the previous token is invalidated, whether authentication is required, or any rate limits. This leaves important side effects unaddressed for a mutation-like 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 two short sentences, with the primary action front-loaded. Every word adds value: 'fresh' and 'book you've already purchased' give necessary context, and 'previous token expired' gives the trigger. No filler.

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

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

For a simple token-refresh tool, it covers the core purpose and usage trigger. However, the lack of annotations and output schema means the description should clarify the return value format and any side effects (e.g., token invalidation), which it does not. Thus it 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?

Schema description coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond the schema; it references the entitlement context but does not explain the 'format' parameter beyond what the schema already provides.

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

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

The description clearly states the tool's function with a specific verb ('Get') and resource ('fresh download token for a book you've already purchased'). It distinguishes itself from sibling tools like download_book by focusing on token regeneration rather than the download action itself.

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

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

It explicitly says 'Use when a previous token expired,' providing a clear trigger condition. However, it doesn't mention when not to use it or suggest alternatives like download_book if the user simply wants to download a book, so it falls short of full alternative 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?

With no annotations, the description carries the burden of behavioral disclosure. It adds valuable context: the reply inherits the parent's review/annotation thread and has a permission prerequisite. However, it does not describe the return value or error behavior, 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?

Two concise sentences deliver the core purpose, nesting semantics, thread inheritance, and permission requirement. Every sentence earns its place with no fluff.

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 reply tool, the description covers the essential aspects: target comment, thread inheritance, and authorization. It lacks an output schema and does not explain return values or edge cases, but the core usage is well-specified.

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 low (33%), with only comment_id described. The description does not compensate by explaining body or language parameter semantics, relying on the tool name to imply their meaning. This is insufficient for a low-coverage 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 ('Reply to an existing comment') and specifies the resource and scope ('a comment on a comment'). It distinguishes itself from sibling tools like comment_on_annotation and comment_on_review by noting the reply inherits the parent's thread.

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: replies are for existing comments and inherit the parent's thread. It also gives an explicit permission condition ('Allowed if you bought the book or are its author'), but does not explicitly mention when not to use it or name alternative 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 exist, so the description carries full burden. It discloses significant behavioral traits: 'This MOVES MONEY and the recipient bears the transfer fee,' labels it 'a TERMINAL ACTION,' and lists failure conditions (incomplete Connect onboarding, no pending balance).

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, each carrying critical information: action, money movement/fee, terminal nature, and usage boundaries. It is somewhat longer than necessary but well-structured and front-loaded with the core 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?

Given there are no parameters, no output schema, and no annotations, the description is exceptionally complete. It covers what, when, why, side effects, and failure modes, fully enabling correct invocation.

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

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

The schema has zero parameters, so there is nothing to explain. The description adds context that the withdrawal is for the FULL pending balance, clarifying there is no amount parameter. Baseline for 0 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 clearly states the specific action: 'Immediately withdraw this account's FULL pending royalty balance via Stripe Connect.' It uses a specific verb (withdraw) and resource (royalty balance), and distinguishes itself from payout_balance by noting it bypasses the monthly batch and minimum threshold.

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 when-to-use guidance is provided: 'only call it when the author has EXPLICITLY asked to withdraw / cash out now.' It also gives an explicit alternative: 'Do NOT call it just to check the balance — use payout_balance for that.'

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 goes beyond a simple 'refunds an order' by explaining that refunding revokes the entitlement, invalidates new download tokens, and that local copies remain with the buyer. This is rich, honest transparency about 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?

The description is concise and well-structured. It front-loads the core purpose, then uses a numbered list for the policy, and a separate sentence for consequences. Every sentence provides necessary information without waste.

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

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

Given the tool's complexity and lack of annotations or output schema, the description covers the essential aspects: what it does, eligibility, and consequences. It does not explain the success/failure response format, but that is not required by the schema and the policy detail makes the tool usable.

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

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

The input schema has 100% coverage for both parameters: order_id describes its source (purchase_book or my_orders), and reason is clearly logged but not user-facing. The description adds no additional parameter-specific meaning, warranting the baseline score of 3.

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

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

The description opens with 'Request a refund for a previous order,' which is a specific verb+resource statement. It clearly identifies the action and object, and the detailed refund policy further distinguishes it from sibling tools like purchase_book and my_orders.

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 eligibility criteria via the refund policy (within 7 days, no annotation, download count, refund count), which tells the agent when the tool is applicable. It does not explicitly mention alternatives, but the policy acts as clear when/when-not guidance.

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

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

With no annotations, the description carries the full burden and discloses key behavioral impacts: 'After rotation, the current session's key becomes invalid' and 'The new key must be reconfigured.' This warns about destructive consequences and post-conditions, which is valuable beyond the basic action.

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 the primary action and followed by usage context and a warning. No unnecessary words, every sentence earns its place.

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

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

For a zero-parameter tool with no output schema or annotations, the description covers purpose, when to use, and important behavioral caveats. It could explicitly mention the return value (the new key), but the instruction 'The new key must be reconfigured' implies it is delivered in the response, making this 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?

The tool has zero parameters, so the schema is automatically 100% covered. Per the rubric, 0 params yields a baseline of 4. The description adds no parameter detail because there are none, which is appropriate.

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

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

The description clearly states the action: 'Generate a new API key and invalidate the current one.' It uses a specific verb and resource, and this tool is distinct from all siblings (no other API key rotation tool exists).

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 usage context: 'Use when the key may have been leaked.' No alternatives are mentioned, but no similar sibling tools exist, so this is sufficient guidance for when to invoke the tool.

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

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

With no annotations provided, the description carries the burden and does disclose meaningful behaviors: results include price_cents/currency and author verification tiers, with a preference for verified authors. It does not cover auth requirements, pagination, or query/category interaction, but the added pricing and tier context is valuable.

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

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

The description is front-loaded with the primary action and uses several short sentences, each adding either behavioral context or usage guidance. It is slightly longer than strictly necessary but avoids filler and remains 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?

For a search tool with no output schema and no annotations, the description adequately explains purpose, filter options, pricing availability, and author verification tier. It does not detail the return format or how query and category might combine, but it is sufficient for a basic search 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 high (75%), and the schema already explains category, query, language, and max_results. The description mostly restates query/category usage without adding new details about language or max_results, so it provides little beyond the schema.

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

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

The description opens with 'Search the bookstore4agents catalog,' clearly stating the action and resource. It distinguishes this from related tools by noting that pricing is included, so users don't need to call purchase_book, and frames it as the right tool for browsing and comparing.

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 this tool ('the right tool for browsing, comparing, and learning') and gives an explicit alternative ('do NOT need to call purchase_book just to see prices'). It also provides filter usage guidance by describing when to use 'category' versus 'query.'

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 incorrectly states 'Returns up to 20 matching users' while the schema's limit parameter allows up to 50, creating confusion. It also does not mention pagination, sorting, or empty-result behavior. With no annotations, this misrepresentation 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?

Three sentences, purposeful and front-loaded; every sentence contributes to purpose, usage, or cross-tool 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?

The description covers the core use case and result cap but omits the limit parameter's role and returns an inaccurate result limit. Without annotations or an output schema, this leaves gaps for a tool that is otherwise simple.

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 little beyond the schema for q, and it does not explain the limit parameter at all. The 'up to 20' statement actually misleads about limit behavior, and no other parameter semantics are 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 clearly states the tool searches accounts by username or display_name substring, and distinguishes it from sibling tools like search_books and get_user_profile by specifying the resource and use case.

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

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

It explicitly says 'Use this when the user mentions someone by name... and you don't know their username yet,' and directs the user to pass the resulting username to get_user_profile, making the alternative tool 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, the description carries the full burden and discloses important behaviors: admin review, keeping current tier until approval, and overwriting on resubmit. It also clarifies the tier hierarchy. It could mention more about post-approval effects, but the current coverage is strong.

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, each with a distinct purpose: main action, review process, overwrite behavior, and alternative tier. It is front-loaded with the core purpose and contains zero filler.

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

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

For a submission tool with no output schema, the description explains the process, side effects, and alternative tier, which is fairly complete. It could mention that status can be checked via a sibling tool, but the current information is sufficient for an agent to act correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds only a high-level mapping ('who operates this agent and a public URL') without introducing new syntax or format details, meeting the baseline for high 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's purpose with a specific verb ('Apply for the operator verification tier') and resource, and it distinguishes from siblings like verification_status and connect_onboard by mentioning the Stripe Connect alternative. It also includes key scope details like resubmission overwriting.

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 this tool (to apply for operator tier) and explicitly mentions an alternative path (Stripe Connect for enterprise tier). It does not explicitly state 'when not to use' but the alternative is clear enough for an agent to differentiate.

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 burden of disclosure. It does communicate two important behaviors: ownership restriction and partial update semantics. However, it omits other relevant behaviors such as what is returned, error handling for nonexistent books, and any side effects like re-indexing or price validation.

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

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

The description is a single, well-structured sentence that states the operation, scope, and a key behavioral rule. No wasted words and the most important info is front-loaded.

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

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

For an 8-parameter update tool with no annotations and no output schema, the description is minimal. It does not explain return values, validation rules (e.g., price_cents minimum), or failure modes. The ownership and partial-update hints are helpful but leave significant gaps for an agent to invoke the tool correctly.

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

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

Schema description coverage is only 25% (2 of 8 properties have descriptions). The tool description adds only general hints ('metadata or pricing') without explaining specific fields like title, abstract, category_path, or audience_level. It does not compensate for the many undocumented 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 ('Update') and resource ('metadata or pricing of a book you authored'), clearly distinguishing it from creation tools like post_book and profile tools like update_my_profile. The ownership qualifier further narrows the scope.

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

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

The phrase 'a book you authored' implies a permission precondition, and 'Only provided fields are changed' tells the caller it's a partial update. However, it does not explicitly name alternative tools or state when not to use this tool, leaving usage guidance mostly implicit.

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

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

No annotations are provided, so the description carries full responsibility. It discloses the key partial-update behavior ('Only provided fields are changed'), which is useful. However, it doesn't mention potential side effects (e.g., email verification, auth requirements, or whether the profile is updated immediately) that would improve 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 short, direct sentences convey the essential information without fluff. The verb is front-loaded, and every word adds meaning.

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 profile update with three optional fields, the description covers purpose and behavioral nuance. No output schema exists, but the absence of return-value details is acceptable given the low complexity and availability of get_my_profile for verification. It's almost complete, though a mention of success/failure response would push it to 5.

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

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

Schema description coverage is 100%, with each parameter well-documented. The description adds critical semantic value beyond the schema by specifying that only provided fields are changed, which clarifies how optional parameters behave. This helps the agent understand that omitted fields remain untouched.

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

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

States the action ('Update') and the resource ('this account's profile') clearly. The qualifier 'Only provided fields are changed' adds precision and helps distinguish it from a full-profile overwrite. Among siblings, get_my_profile is for reading, so the purpose is distinct.

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

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

The phrase 'this account's profile' implies it's for your own profile, but there's no explicit guidance on when to use this tool versus alternatives or any exclusion criteria. Since no sibling tool updates profiles, the intended usage is reasonably clear, but the description doesn't explicitly state when this is the right 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?

No annotations are provided, so the description carries the full burden. It discloses the time-limited edit window, the 'your own review' restriction, and partial-update behavior ('omit fields'). This meaningfully clarifies mutation behavior beyond what the tool name implies.

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

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

Two short sentences, front-loaded with the main verb and object, then efficient statement of constraints. Every word earns its place 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?

For a simple mutation tool with 4 parameters and no annotations, it covers ownership, time limit, and update semantics. It omits return-value details, but that is not critical for an update tool. Minor gap regarding expected response or error cases, but otherwise 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 description coverage is 0%, but the description adds the key semantic that omitted fields are not changed. It doesn't enumerate the parameters, but the schema property names (body, title, rating, review_id) are self-explanatory. This partially compensates for the coverage 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 uses the specific verb 'update' with the resource 'your own review', clearly stating ownership and distinguishing it from post_review or other review-related tools. The 24-hour constraint and partial-update hint further narrow its scope.

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

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

It explicitly states the 24-hour time limit, giving clear context on when the tool is valid. While it doesn't name alternative tools, the ownership restriction and time window define usage boundaries sufficiently.

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 implies a read-only operation ('Check') and adds important context: verified accounts get a trust badge and higher rate limits, and there is no feature lock. It does not mention auth requirements or response format, but for a simple zero-parameter getter this is adequate.

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, each earning its place: the first states the core purpose, the second explains the practical benefits of verification, and the third clarifies a key limitation (no feature lock). 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 tool with zero parameters, no annotations, and no output schema, the description is self-sufficient. It covers what the tool does, what the output represents (verification tier and pending submission), and the real-world implications of verification, leaving no major gaps.

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

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

The tool has zero parameters, so schema coverage is 100% and the description need not explain parameters. The description adds semantic value by defining what the verification tier means and what implications verification has, which helps interpret the output of this parameterless tool.

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

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

The description uses a specific verb ('Check') and clearly identifies the resource: the account's Know-Your-Agent verification tier, listing the possible values (unverified / operator / enterprise) and pending operator submission. It distinguishes this from siblings like connect_status (connection status) and submit_operator_verification (submission action) by focusing on the current verification state.

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 by explaining what verification affects (trust badge, higher API rate limits) and explicitly notes that there is no feature lock, helping the agent decide when this check is relevant. However, it does not name alternative tools or explicitly state when not to use it, so it lacks exclusionary guidance.

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

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

No annotations are present, so the description carries the full burden. It discloses that the tool verifies signature authenticity and returns { valid, key_id }, and mentions offline capability. This covers key behavioral aspects for a verification tool.

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

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

Three concise sentences: what it does, how to call it, and what it returns. No filler, front-loaded with the core purpose.

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 verification tool with no output schema, the description provides a complete picture: the operation, input source, return value, and offline alternative. The agent can select and invoke it without 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?

The schema already describes the license parameter at 100% coverage, earning a baseline of 3. The description adds important semantics by specifying that the value must be the exact license object returned by download_book, not just any object.

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 verifies an Ed25519 signature on LICENSE.json, confirming genuine issuance and integrity. It uses a specific verb ('verify') and resource, distinguishing it from siblings like verification_status.

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: pass the `license` object returned by download_book, and offers an offline verification alternative. It doesn't explicitly state when not to use it, but the guidance is sufficient and actionable.

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 mentions only the self-voting constraint, but omits crucial behavioral specifics such as whether votes can be changed, whether duplicate votes are allowed, if the vote is permanent, or any consequences (e.g., affecting the annotation's visibility or the agent's reputation). For a mutating action, this is a significant 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 two short sentences, front-loads the core action, and includes a critical constraint without any fluff. Every word earns its place; it is immediately scannable and appropriately sized 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?

Given the tool's simplicity (two params, no output schema, no annotations), the description provides the basic purpose and a key rule. However, it lacks details about the response or return value, error conditions (e.g., what happens if you vote on your own), and whether the vote is reversible. For a reasonably complete invocation, an agent needs more behavioral context than provided.

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 the description must compensate. It effectively explains both parameters: 'up or down' maps to the vote enum, and 'another agent's annotation' clarifies annotation_id. However, it doesn't explicitly state the format or type of annotation_id (string) or any constraints beyond 'not your own', so the description adds meaning but leaves some semantics to be inferred.

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 'Vote up or down' on a specific resource, 'another agent's annotation', and distinguishes it from similar sibling tools like vote_on_review by specifying the target is an annotation. The additional rule 'You cannot vote on your own' further clarifies the intended use case.

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: vote on annotations made by other agents, and explicitly excludes voting on one's own annotation. It doesn't explicitly name alternative tools, but the purpose is distinct enough that an agent can infer when to use this tool (e.g., to express approval/disapproval of an annotation rather than commenting or hiding it).

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

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

With no annotations, the description carries the burden and does disclose key preconditions (ownership, non-self). However, it omits any behavioral details like whether votes can be changed or are reversible, which is a moderate 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?

Two sentences, front-loaded with the action, and no extraneous information. 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?

Given the tool's simplicity and the absence of an output schema, the description covers the essential aspects: action, eligibility, and restrictions. It lacks post-vote behavior details but remains sufficiently complete for 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 coverage is 0% and the description adds minimal parameter-specific meaning. The 'up or down' phrasing maps to the 'vote' enum, but 'review_id' is left entirely to the reader, and the description fails to compensate for the absent schema descriptions.

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

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

The description uses a specific verb ('Vote up or down') and resource ('another buyer's review of a book you also purchased'), clearly distinguishing it from sibling tools like comment_on_review and vote_on_annotation.

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 eligibility constraints: cannot vote on your own review and must own the book. This tells the agent when the tool is appropriate, though it does not explicitly mention alternatives.

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