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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the useful detail that the page is 'public' (implying no auth or private-access path), but says nothing about rate limits, failure modes (e.g., unknown author_id), or what the returned page contains. With annotations carrying the safety profile, this is an adequate but thin contribution.

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

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

Two short sentences, front-loaded with the action and resource, with nothing superfluous. It is perhaps slightly too terse — a single clause about what the fetch returns would earn its place — but there is no padding or redundancy.

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

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

For a one-parameter read-only tool whose annotations and schema are both fully populated, the definition is serviceable. However, with no output schema and no note about return content or error behavior for invalid author_id, an agent still has to guess at the result shape.

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

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

Schema description coverage is 100% and the single parameter is documented, so the schema does the heavy lifting. The description only restates that author_id is required, adding no format, source, or example beyond what the schema provides — baseline 3 applies.

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

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

The description states a specific verb and resource ('Fetch a public Goodreads author page'), which is clear enough for an agent to identify the operation. It does not explicitly differentiate from book_get or the goodreads-search_books siblings, but the resource noun (author page) does most of that work implicitly.

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

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

There is no guidance on when to use this tool versus siblings like book_get or goodreads-search_books, nor on how to obtain a valid author_id. The word 'public' hints that no authentication is needed, but no conditions, prerequisites, or exclusions are stated.

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

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

Annotations already declare readOnlyHint, openWorldHint, destructiveHint=false, so the safety profile is covered. The description adds only 'public', which usefully implies no authentication is required. It says nothing about rate limits, failure modes for missing ids, or whether the result is raw HTML versus parsed data.

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

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

Two compact sentences with the action first and the requirement second. Nothing is wasted or buried.

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

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

With no output schema, the description should indicate what a 'page' fetch returns (parsed fields, raw HTML, or a summary). As written, an agent can call it but cannot anticipate the response shape.

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

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

Schema coverage is 100% and the single parameter is documented as 'Book id'. The description merely restates that book_id is required, adding no format, sourcing, or example detail beyond the schema.

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

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

States a specific verb ('Fetch') and resource ('public Goodreads book page'), which is enough to tell it apart from author_get or review_get-shelf by resource noun alone. It stops short of explicitly contrasting itself with those siblings, but the resource is unambiguous.

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

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

No guidance on when to call this versus goodreads-search_books (to find a book_id first) or the enrich/sync tools. The agent must infer the lookup-to-fetch workflow entirely on its own.

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

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

Annotations already disclose readOnly and openWorld. Description adds what the context contains but does not contradict annotations.

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

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

Two concise sentences, no wasted words. Front-loaded with action 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?

Given zero parameters and no output schema, the description fully covers what the tool does and when to use it.

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

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

No parameters exist; baseline 4 per instructions. Description adds no parameter info, but none 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?

Clearly states the tool retrieves API domain context including specific items (resource taxonomy, auth requirements, etc.). Distinct from sibling action 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?

Explicitly says 'Call this first', providing clear temporal guidance. Does not explicitly name alternatives but context implies using siblings for subsequent actions.

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 annotations declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, yet the description frames the tool as a benign 'resolve ... to metadata' operation. Nothing in the text warns that this may mutate or destroy data, what the destructive action targets, or that authentication/open-world network access is involved, so the described behavior conflicts with the declared safety profile.

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?

It is a single front-loaded sentence with no filler, which is structurally sound. The brevity is not wasteful per se, but it leaves the one sentence doing too little work for a 23-parameter 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?

For a destructive, open-world tool with 23 parameters, no output schema, and Notion-sync implications, one sentence is seriously incomplete. An agent gets no warning about writes, no interaction with the idempotent/dry-run flags, and no explanation of how 'enrich' differs from 'sync' or 'book_get'.

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 23 parameters are documented at 100% schema coverage, so the schema already carries the semantics and a baseline of 3 applies. The description adds no extra meaning about the key input (book-id or title) or how the output-control flags interact with the sync purpose.

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

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

The description gives a clear verb ('Resolve') and resource ('a title or Goodreads book ID') plus the output ('metadata'). However, it never distinguishes itself from close siblings like book_get or goodreads-search_books, so an agent cannot tell from the text alone why it should pick this tool over those.

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

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

There is no when-to-use guidance, no mention of alternatives, and no preconditions. With siblings such as book_get and goodreads-search_books performing overlapping lookups, the description offers no routing help at all.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The phrase 'public Goodreads book pages' loosely corroborates the open-world nature, but the description does not explain the notable idempotentHint=false, whether results come from live scraping, or whether rate limits apply.

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

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

Two short sentences, front-loaded with the action. The second sentence is largely redundant with the schema's required array, so it does not fully earn its place, but there is no bloat.

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 search tool with no output schema, the definition is minimally viable but thin. It says nothing about result shape, result count, or whether the search hits the live site versus a cached index, all of which an agent would want before calling.

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

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

Schema coverage is nominally 100%, but the only schema description is the single character 'Q', which conveys nothing. The description's 'Required: q' merely repeats requiredness, leaving the agent with no idea what the query string should contain or how it is matched.

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

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

The description names a specific verb and resource: search public Goodreads book pages. That is enough to separate it from book_get and author_get, which retrieve a single known entity, but it never explicitly states the distinction or what the search matches on (title, author, ISBN).

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

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

There is no when-to-use or when-not-to-use guidance, and no mention of when to prefer book_get or enrich instead. 'Required: q' is a parameter constraint, not usage guidance.

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

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

Annotations already flag destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: per-record POSTs and partial-failure semantics (failed records logged to stderr, import continues). It does not mention confirmation prompts, the idempotent or dry-run flags that mitigate destructiveness, or rate limiting, which matter a lot for a destructive bulk-write.

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

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

Three short sentences, front-loaded with the action and mechanism, followed by the file format constraint and failure behavior. Nothing is padded, though the format constraint partially restates the schema description of `input`.

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

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

For a destructive bulk-write with 23 params and no output schema, the description covers the core semantics an agent needs: the input format, the write mechanism, and non-atomic failure handling. What's missing is where records land and how to preview safely (dry-run), but those gaps are partly bridged by the schema.

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

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

Schema coverage is 100%, so each of the 23 parameters is already documented in the input schema. The description only clarifies the format expectation for the required `input` file (one JSON object per line), adding little beyond the schema baseline.

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

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

States a concrete verb+resource: import records from a JSONL file via per-record POST requests. That distinguishes it from read-oriented siblings like book_get or sql, but it never names the target resource (presumably Goodreads shelves) nor contrasts with sync or enrich, which are the closest alternatives.

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

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

No statement of when to use import versus sync, enrich, or workflow_* tools, and no mention of prerequisites such as auth or a prior sync. The agent must infer usage entirely from the name and schema.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds that the shelf is public, which is useful context about access scope, but it does not mention authentication, rate limits, pagination, or default shelf 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 tight sentences with zero waste, front-loading the main action and then the parameter requirements. 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 simple two-parameter read tool with annotations covering safety, the description is adequate but incomplete. It does not say what shelf is fetched by default when 'shelf' is omitted, nor does it describe pagination or return shape, and there is no output schema to compensate.

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 both parameters. The description reiterates required/optional status and adds no format, valid values, or default behavior for 'shelf' or 'user_id,' so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Fetch') and resource ('public Goodreads user shelf page'), which is clearer than a generic shelf tool. It does not explicitly distinguish itself from siblings like shelf_auth_check or goodreads-search_books, so it stops short of a 5.

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

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

It lists required and optional parameters but gives no guidance on when to use this tool versus alternatives such as shelf_auth_check or goodreads-search_books. The closest thing to usage context is the word 'public,' which implies access to public shelves only, but this is not developed into explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, and idempotentHint=false. The description adds no behavioral context about what validation actually does, whether it sends a real write request, what side effects are possible, or what credentials are needed.

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

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

A single sentence with no filler, and the purpose is front-loaded. It is terse for a 20-parameter tool, but that is a completeness issue rather than wasted prose.

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 20 optional parameters, open-world access, a destructive hint, and no output schema, the description is too thin. It does not explain the validation result, required auth context, or how it relates to write siblings such as shelf_set and shelf_rate.

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 20 parameters have schema descriptions (100% coverage), so the schema carries the parameter semantics. The description adds no parameter-level meaning, which is acceptable at the baseline 3 but leaves the generic CLI flags entirely to the schema.

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

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

States a specific verb (validate) and resource (Goodreads write authentication). It distinguishes the check from read-oriented siblings like book_get, but does not clarify what 'authentication' entails or name related write 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?

Provides no explicit when-to-use guidance, prerequisites, or alternatives. The description only implies that it should be run before write operations; the agent must infer that context.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is known. The description adds nothing beyond that: it doesn't say whether an existing rating is overwritten, whether auth is required, or what the result looks like, despite this being a destructive mutation with 23 parameters.

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

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

One short, front-loaded sentence with no filler. It is efficient, though the brevity edges into under-specification rather than genuine concision.

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

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

For a destructive, non-idempotent mutation with 23 parameters and no output schema, the description is far too thin. It should at minimum cover overwrite behavior, auth requirements, and the relationship to shelf_set/shelf_unrate.

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 parameters such as rating (1 to 5) and book-id are already documented in the schema. The description adds no syntax or format detail beyond that, which is acceptable given full coverage — baseline 3 applies.

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

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

States a specific verb and resource: set a Goodreads rating for a book. That is unambiguous about what the tool does, but it never distinguishes itself from close siblings such as shelf_unrate or shelf_set, so an agent must guess which one applies.

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

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

There is no guidance on when to use this versus shelf_set or shelf_unrate, nor any prerequisites such as authentication or whether the book must already be on a shelf. Usage has to be inferred entirely from the name.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the description should add context such as whether re-shelving overwrites a prior shelf, whether auth is required, that it makes a live network call, or that it prompts for confirmation. None of that is present; the description adds nothing beyond the annotations and leaves the destructive overwrite semantics unexplained.

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

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

A single front-loaded sentence with no wasted words. It is efficient, though the brevity borders on under-specification given the 27-parameter surface.

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

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

This is a destructive, non-idempotent mutation with a very large parameter surface, no output schema, and no stated return format or auth requirements. One sentence cannot adequately prepare an agent to invoke it safely.

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% across all 27 parameters, so the schema carries the burden and baseline 3 applies. The description does not clarify the required 'book-id'/'shelf' pairing or note that 'started-at' and 'finished-at' are unsupported no-ops, but repeating schema text is not 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?

A specific verb ('Mark') and resource ('a book') plus the three target shelves, so the action is unambiguous. However it never names a sibling it differs from, and the closest neighbor, shelf_unshelve, removes books from a shelf — the description does not help an agent tell these apart.

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 sentence describes what the tool does but gives no guidance on when to prefer it over shelf_unshelve or shelf_rate, no prerequisites (authentication, existing shelf state), and no mention of the confirmation behavior implied by the 'yes' and 'no-input' parameters.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds nothing beyond that: it doesn't say what happens if no rating exists, whether a confirmation prompt fires (relevant given the 'yes' parameter), or whether the removal is reversible.

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

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

A single front-loaded sentence with zero filler. It is efficient, though the brevity comes at the cost of the targeting detail (book-id) an agent actually needs to invoke it.

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

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

For a destructive mutation tool with 22 parameters, no required fields, and no output schema, the description is too thin. It should at minimum identify the book-id as the targeting input and note confirmation behavior, neither of which is stated.

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

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

Schema description coverage is 100%, so all 22 parameters are documented in the schema and the baseline is 3. The description adds no parameter guidance, notably omitting that 'book-id' is the essential input despite no required parameters being marked.

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

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

States a specific verb (remove) and resource (your Goodreads rating for a book), which is clear enough to distinguish from shelf_rate and shelf_set by implication. It stops short of naming those siblings explicitly or noting the shelf scope, so it's clear but not maximally differentiating.

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 verb 'remove' implies the inverse-of-rate use case, so an agent can infer when to reach for it. There is no explicit guidance on when to use this versus shelf_set, shelf_unshelve, or shelf_rate, and no mention of prerequisites such as the book needing an existing rating.

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 annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds essentially no behavioral context beyond those annotations: it does not mention that a confirmation prompt may appear, what gets removed, whether it affects multiple shelves, or how the operation behaves if the book is not on the shelf. Given the destructive nature, this is thin.

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

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

The description is a single front-loaded sentence with no wasted words. It is appropriately sized for conciseness, though that conciseness comes at the cost of useful detail for a destructive tool with 22 parameters.

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

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

For a destructive 22-parameter tool with no output schema, the description is insufficiently complete. It does not mention the likely required book identifier, confirmation prompts, dry-run behavior, or whether removal applies to all shelves. The schema covers the parameters, but the description should still prepare the agent for the destructive nature of the call.

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

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

Schema description coverage is 100%, so all 22 parameters are documented in the schema itself. The description adds no parameter-level meaning, so the baseline 3 is appropriate. It does not explain which parameters matter most for this specific operation, such as book-id, yes, or dry-run.

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

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

The description states a specific verb and resource: remove a book from Goodreads shelves. It clearly distinguishes itself in intent from shelf_set, shelf_rate, and shelf_unrate. It does not explicitly name its siblings or clarify whether it removes from a specific shelf versus all shelves, which keeps it from a 5.

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

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

There is no guidance on when to use this tool versus alternatives like shelf_set or shelf_unrate, nor any mention of prerequisites such as authentication or confirmation handling. The description only restates what the tool does, leaving selection conditions for the agent to infer.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is carried by structured data. The description adds a real prerequisite ('Requires sync first') not present in annotations, but says nothing about row limits, timeouts, cost, or what happens for invalid/non-SELECT queries.

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

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

Three short sentences, front-loaded with the core action, then use case, then prerequisite. No filler; every sentence earns its place.

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

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

For an open-ended SQL tool with no output schema, the description covers what it does, when to use it, and the sync prerequisite. The main remaining gap is table/schema discovery guidance (which sibling to call to learn available tables and columns) before writing a query.

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

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

With a single parameter at 100% schema description coverage, the schema already explains the query string and the SELECT/WITH...SELECT restriction, so baseline is 3. 'Tables match resource names' is useful but duplicated in the schema, adding no new meaning.

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

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

States a specific verb and resource ('Run read-only SQL against local database') plus the intended use case (ad-hoc analysis, aggregations, joins). It is clearly distinguishable from the CRUD-style siblings (author_get, book_get, review_get-shelf), though it never names those siblings explicitly.

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

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

'Use for ad-hoc analysis, aggregations, and joins across synced resources' gives clear positive guidance, and 'Requires sync first' states a prerequisite. It stops short of naming alternatives (e.g., the context tool for schema discovery) or when-not-to-use cases.

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 adds substantial behavior beyond the annotations: denied resources are warnings rather than hard failures, JSON warning/summary events are emitted, and exit status depends on critical-resource policy and --strict. This is exactly the kind of operational context an agent needs for a non-idempotent, open-world sync.

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 core purpose and search handoff are front-loaded, and the exit-code section is organized under a clear heading. The exit-policy prose is dense and quite long, but it remains relevant for a sync tool whose failure semantics matter.

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 rich schema and annotations, the description covers the essential sync model, incremental/full behavior, warnings, and exit codes. It does not explicitly restate destructive local-write implications or authentication requirements, but the destructive and open-world annotations already signal those risks.

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

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

With 100% schema description coverage across 28 parameters, the schema already carries most parameter meaning. The description adds useful context for 'since', 'full', 'strict', and '--json' behavior, but it does not systematically explain the many output, routing, cache, concurrency, and resource-selection 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 states a specific verb and resource: syncing API data into a local SQLite database. It also distinguishes the post-sync query path by naming the 'search' command, so an agent can tell what this tool is for without opening the schema.

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

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

It clearly frames the tool as populating local data for later search and explains incremental vs. full resync and when to use --strict. It does not explicitly exclude or compare against siblings such as 'import' or 'sql', so it stops short of full when/when-not guidance.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, so the agent knows this is a mutating, network-bound operation; the description adds useful detail that it writes to a local SQLite database and supports incremental sync. But it never explains what the destructive flag means in practice—whether existing archived data is overwritten or merged, whether confirmation is required (the 'yes' param implies it), or that the run may be long due to remote fetching.

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 tight sentences, front-loaded with the core action before the incremental/full variants. The trailing pointer to 'search' is efficient but references a command not present among siblings, slightly diluting the value of that sentence.

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

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

Given 22 flags, no output schema, and destructive/open-world annotations, the description covers the essential 'what it does and how it differs across modes' story. It leaves out return-value shape and confirmation behavior, but for an archival command whose flags are fully in the schema, this is reasonably 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 all 22 parameters are already documented, establishing the baseline of 3. The description reinforces the semantics of the 'full' flag (full resync vs incremental) but does not mention any parameter by name or clarify the interaction of 'agent', 'yes', 'dry-run', or 'data-source' with this command.

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

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

States a concrete verb and resource: fetch all syncable resources from the API and persist them into a local SQLite database. The incremental-vs-full distinction is spelled out. It does not, however, distinguish itself from close siblings like 'sync' and 'import', leaving the agent to infer which one performs the local archive.

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 a workflow (archive first, then use 'search' for full-text search), which is useful routing, but 'search' is not one of the actual sibling tools (the closest are 'sql' and 'goodreads-search_books'). No guidance is given on when to choose this over 'sync' or 'import', or on prerequisites such as authentication.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds that the scope is local archive status and sync state across all resources, but it does not elaborate on auth, rate limits, caching, or what the returned status includes. It adds some scope context without contradicting the annotations.

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

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

A single front-loaded sentence with no filler. It communicates the core scope immediately and is appropriately sized for a status command.

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

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

There is no output schema, and the description does not explain what 'status' or 'sync state' contains. For a 21-parameter status tool, the minimal description is adequate to identify the command but leaves output expectations and practical usage context under-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 100%, so all 21 parameters already have structured descriptions. The tool description adds no parameter-level meaning beyond that, which makes the baseline score of 3 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 verb and resource: 'Show local archive status and sync state for all resources.' This is clearly a read-only status tool, distinguishable in kind from siblings like workflow_archive and sync, though it does not explicitly name those alternatives.

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

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

It gives no explicit guidance on when to use this tool versus workflow_archive, sync, or other siblings. The scope 'for all resources' is stated, but there are no usage conditions, prerequisites, or exclusions.

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