siftivo

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

Annotations only flag destructiveHint/idempotentHint/readOnlyHint=false; the description explains the actual risk: 'Each field given replaces what the reader had there before', so callers must not resend a rating or note unless it should change. It also discloses the auth prerequisite ('Needs a linked Siftivo account') and the no-op semantics of omitting readingStatus, all beyond structured 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?

Front-loaded with the core action and shelf values, then routing, then replace semantics. It is dense and the worked example phrases slightly overlap with the usage sentence, but nearly every sentence carries distinct information and none is 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 5-parameter mutation with no output schema, the description covers the operation, prerequisites, defaults, and overwrite behavior well. It does not say what happens on an unknown workId or a failed write, which is the only notable gap.

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

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

Schema coverage is already 80% (notes, rating, progress, readingStatus all documented), so the baseline is 3. The description adds genuine meaning on top: workId provenance (search_books), the combined readingStatus+rating pattern with a worked 4.5 example, and the replace-not-merge semantics of each field.

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

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

States a specific verb and resource (add/log reading on the reader's shelves) and enumerates the exact operations: shelving to NOT_STARTED/READING/FINISHED/DNF, rating, progress. It is clearly separable from siblings like remove_from_library and get_my_library without opening any schema.

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

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

Gives concrete user phrasings that should route here ('add X to my list', 'I just finished X, four stars', 'I'm halfway through X') and names search_books as the source of workId, so the agent knows the prerequisite call. It also states the default behavior when readingStatus is omitted, removing the main ambiguity about when a minimal call is appropriate.

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=false and destructiveHint=false, so safety is covered. The description adds the content scope (biography + books + years, limited to Siftivo holdings), which aids selection, but says nothing about behavior for unknown authors, partial matches, or result size.

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

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

Two sentences, zero waste: content and scope first, then the intents that select it. Every clause earns its place.

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

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

With no output schema, the description usefully enumerates what comes back (biography, books, years), and the single-parameter surface is fully covered. Minor gaps remain around ambiguous-name resolution, but nothing needed to invoke it is missing.

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

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

Schema coverage is 100% and the description's id guidance ("author name, an author id, or a siftivo.com slug") is essentially identical to the schema description. Baseline 3 applies since the schema does the parameter work.

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

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

The description names a specific resource (author) and states exactly what is returned: a biography plus Siftivo's holdings for that author with years. It is clearly distinct from get_book/get_series by resource, though it never names a sibling to route against.

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 concrete user intents that select this tool – "what else has X written" and "tell me about X" – which is stronger than implied usage. It stops short of naming a when-not condition or an alternative tool for author lookups.

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=false, so safety is covered. The description adds genuinely new behavioral context: results are personalized ('the result says why') only when the reader has linked a Siftivo account, which an agent cannot infer from 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?

Front-loads what the tool returns, then usage scenarios, then input provenance — a sensible ordering with little waste. It is slightly dense with quoted example questions, but every sentence carries selection or invocation information.

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

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

With no output schema, the description compensates by listing the fields returned (synopsis, authors, year, series position, genres, page), so the agent knows what to expect. The remaining gap is minor: no note on behavior when an id is not found or when no account is linked beyond the taste feature.

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

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

Schema coverage is 100% for the single id parameter, so the baseline is 3. The description goes further by explaining provenance and accepted forms — a workId from search_books, or a siftivo.com slug — which tells the agent where to obtain a valid value and that slugs are acceptable.

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?

Opens with a specific verb+resource ('What one book is about') and enumerates the returned fields (synopsis, authors, year, series and position, genres, page), which clearly separates it from get_series, get_author and get_my_book. An agent can identify the tool without opening the schema.

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

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

Gives concrete usage scenarios ('what is X about', 'is X part of a series', and the account-linked 'would I like X') and names search_books as the upstream source of the id. It stops short of explicit exclusions against siblings like get_my_book or get_series, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already establish readOnly, non-destructive and non-open-world behavior, and the description adds genuinely new context on top: a linked Siftivo account is required, and titles absent from the catalog are returned under 'unmatched'. That auth prerequisite and edge-case return behavior go beyond the annotations, though no rate limits or empty-result behavior are described.

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 dense sentences with no filler, and the return contents, accepted inputs, use cases and prerequisites each earn their place. The opening is a relative-clause fragment rather than a front-loaded verb, which slightly weakens the lead, but the overall length is appropriate.

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

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

With no output schema, the description does the work of explaining returns (shelf, rating, progress, unmatched bucket), accepted input forms, auth requirements and usage scenarios. It is nearly complete for a single-parameter read tool; only explicit guidance on the sibling get_my_library and behavior on empty matches is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real resolution heuristic — that '"Title by Author" resolves best' — which the schema only states as an option without ranking it. It also echoes the 25-item cap, reinforcing the schema constraint rather than merely restating it.

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 resource and scope: it looks up which of up to 25 books the signed-in reader already has on a shelf, returning shelf, rating and progress. That is far more concrete than the singular title ('Get one book'), and an agent can understand the batch-membership-check nature. It does not explicitly distinguish itself from the sibling get_my_library, 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 names concrete scenarios — 'have I read X', 'which of these have I read', and vetting a list of suggestions — which is strong when-to-use guidance. It lacks any explicit when-not-to-use or pointer to alternatives such as get_my_library for browsing the whole shelf, so it does not reach 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond that: it requires a linked Siftivo account and discloses that private notes and ratings are included in the payload. It says nothing about library size or result caps.

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 resource and payload, then usage intents, then the prerequisite. Every sentence carries information; nothing is padding.

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

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

With no output schema, the description usefully enumerates the returned fields and states the auth prerequisite, which is enough for an agent to call it correctly. It omits any indication of volume, pagination, or ordering for a potentially large library, which is the only real gap.

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

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

Schema description coverage is 100% and the single status enum is already fully documented with its own 'Omit for the whole library' note. The description's "Filter to one shelf with status" slightly reinforces the shelf-to-status mapping but adds no format or behavioral detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource — the signed-in reader's Siftivo shelves — and enumerates the four shelf categories plus the payload (ratings, progress, private notes). It is clearly distinguishable from single-item siblings like get_my_book and from get_my_taste.

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

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

Gives concrete intent examples ("what am I reading", "what is on my to-read list", "what have I finished") and the prerequisite of a linked Siftivo account, plus when to use the status filter. It never names a sibling alternative or an exclusion case, so it stops 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?

Annotations already declare this a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the safety burden is off the description. It still adds real context: a linked Siftivo account is required, 40 entries return by default, and the data is the same profile the app's own recommendations use — the last point tells the agent the output is authoritative rather than a sample.

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

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

Front-loaded with what the profile contains, then routing conditions, then operational notes. Three dense sentences with no filler, though the opening enumeration is long enough to be slightly heavy for a single-parameter read 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?

There is no output schema, so the description must characterize the return — and it does, listing the entry types, the ranking (strongest first), the default size, and the reasons attached to each entry. Combined with the account-linking prerequisite, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100% and the single parameter is fully documented with default, min and max, so the schema does the heavy lifting. The description's "strongest 40 entries come back by default, and limit raises that" restates the schema default and ranking order without adding new syntax or format detail.

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

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

States a specific resource — the signed-in reader's taste profile — and enumerates its contents (books, authors, series, genres, moods, avoidances, reasons, range). It is clearly distinguishable from siblings like get_my_library or get_reading_index, which cover library holdings and reading activity rather than preference.

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

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

Gives explicit trigger phrasings ("what should I read next", "recommend me a book", "something I would like") and an explicit exclusion: use it only "when no book or mood is named", which implicitly routes the agent to recommend_from_description or recommend_from_titles in the other case. That is genuine when/when-not routing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the description needn't repeat safety. It adds that the data is weekly and ranked, but doesn't mention return format, pagination, or whether the week parameter affects the index beyond the schema note. With annotations covering safety, this is adequate but not rich.

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 resource and contents, then example queries. No wasted words.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose and typical use. It could mention the shape of the result (e.g., list of books with ranks), but it's largely complete given the tool's simplicity.

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

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

Schema coverage is 100%, so the schema fully documents the week parameter (pattern, optionality). The description adds no further parameter-specific meaning; 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 a specific resource (the weekly Siftivo Reading Index) and what it contains (ranked fiction and nonfiction books, weeks on chart, new entries). It is clearly distinguishable from siblings like search_books or recommend_from_titles.

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 example questions the tool suits ('what books are popular right now', etc.), which implies when to use it. It does not explicitly exclude alternatives like search_books, but the context is clear enough.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description then adds real behavioral value by disclosing the returned structure (ordered books with position/publication year plus a completeness signal), which the agent could not infer from annotations alone. It does not cover error behavior for an unknown series, which keeps it at 4.

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 filler: the first front-loads the return shape, the second front-loads the accepted input and its source. Every clause earns its place.

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

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

With no output schema, the description carries the burden of describing the response and it does so adequately (ordered books, position, year, completeness). It omits edge cases such as unknown series names and whether long series are paginated, a minor gap for a one-parameter read tool.

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

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

Schema coverage is 100% and the single parameter's description already lists id, URL slug, or name, so the baseline is 3. The description goes slightly beyond by indicating the id can be obtained from get_book or what_to_read_next, giving the agent provenance for valid inputs, but adds no format or validation nuance.

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

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

The description states a specific verb+resource and enumerates exactly what is returned: every book in reading order with position, publication year, and a completeness flag. It is clearly distinguishable from siblings like get_book (single book) and what_to_read_next (recommendation), since it is the only tool that returns an ordered series list.

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 concrete user intents that fit this tool ('what order do the X books go in', 'what is book 3 of X', 'is the next X book out') and tells the agent where to source the input id (get_book or what_to_read_next). There is no explicit when-not guidance or statement of what to use instead for adjacent needs, 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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description adds real behavioral context the annotations cannot: results are personalized for linked accounts, exclude books already in the library or hidden/avoided/passed-on, and include a rationale when a result fits the reader's taste.

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 the illustrative examples are front-loaded in a single dense sentence, with personalization behavior following. It is longer than most descriptions but nearly every clause carries information; the only slack is the extended list of exclusion categories.

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 usefully sketches what comes back (personalized, filtered results with an explanation when taste matches) and how input is interpreted. The missing piece is semantics for limit/isFiction, which the description never touches despite low schema coverage.

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

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

Schema description coverage is only 33%, so the description must compensate. It enriches the 'description' parameter well by characterizing it as free-form mood/theme/subject language, but says nothing about 'limit' or 'isFiction', leaving two of three parameters undocumented anywhere. Adequate but with a clear 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?

States a specific verb and resource (book recommendations) and explicitly delimits the matching mode: 'Matches on meaning rather than on a title or an author name.' This distinguishes it cleanly from recommend_from_titles without the agent needing to open either schema.

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

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

Concrete example queries ('cozy fantasy with found family', 'a good book about grief') show the intended input shape, and the semantic-vs-title contrast implies when to pick this over a title lookup. It stops short of naming the sibling recommend_from_titles as the explicit alternative, so the routing is clear but not fully spelled out.

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

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

Beyond the annotations' readOnly/openWorld/destructive safety profile, the description discloses genuinely non-obvious behavior: titles are resolved against the catalog with unresolved ones reported rather than guessed, same-author books are excluded, and for linked accounts the results exclude library holdings, hidden, avoided and recently-passed books with an explanation of why a result fits. This is the substantive behavioral context an agent needs and could not get from the annotations or schema.

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

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

The opening leads with the core purpose plus concrete example prompts, then layers behavioral detail (resolution, exclusions, personalization) in short clauses. Every sentence carries information; the only cost is that the personalization clause is a long run-on that could be split.

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

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

There is no output schema, so the description does the work of explaining exclusions and personalization, which it does well. The remaining gaps are the unexplained limit and isFiction parameters and no statement of what the returned items look like beyond 'says why', which keeps it from full marks.

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

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

Schema description coverage is only 33%: only 'titles' is documented in the schema, and the description largely restates that. Neither 'limit' (range/default) nor 'isFiction' is explained anywhere, and the description gives no hint about what isFiction filters or how the result count is bounded. With two of three parameters undocumented, the description fails to compensate 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 states a concrete verb and resource ('Book recommendations from books the reader already loved, named by title') and gives example queries that pin down the input form. It is clearly distinguishable from the sibling recommend_from_description by taking titles rather than a free-text description, but it never names that sibling, so the differentiation is inferred rather than stated.

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

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

Usage context is well sketched: readers who loved specific books, multi-title prompts ('I loved Circe and Piranesi'), and book clubs that enjoyed one pick. It also states an exclusion (other books by the same authors are left out). It stops short of telling the agent when to prefer recommend_from_description or what_to_read_next instead.

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 destructiveHint=true already declared, the description adds critical detail beyond the annotation: what is destroyed (shelf, progress, notes) and the notable exception (rating is preserved). It also discloses the prerequisite of a linked Siftivo account. This is exactly the extra context the annotation alone does not provide.

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 compact sentences with zero waste: outcome and side effects first, then the sibling alternative, then the account prerequisite. Front-loaded and easy to scan.

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 destructive tool with no output schema, the description covers outcome, side effects, alternative, and prerequisites. The only missing piece is guidance on the workId parameter, which keeps it from a perfect score.

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 there is only one parameter (workId), which the schema names but does not describe. The description does not explain the workId parameter (e.g., where to obtain it, format). Baseline for 0% coverage is not automatic; here the description is silent on the sole parameter, leaving a gap, though low complexity limits the impact.

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 ('Take a book off the signed-in reader's shelves entirely') and explicitly distinguishes the tool from its sibling add_to_library by explaining the shelf-move case. An agent can select it without ambiguity.

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

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

It names the alternative ('Moving a book between shelves is add_to_library with a new readingStatus') and provides example phrasings ('take X off my shelves', 'remove X from my list'). When-to-use and when-not-to-use are both covered explicitly.

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, openWorldHint=false, so the safety profile and the closed-catalog scope are covered. The description adds that the result is a workId consumed by other tools, but says nothing about match quality (exact vs fuzzy), result ordering, or how the default limit of 10 behaves when there are many matches.

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, purpose and return value front-loaded before the usage examples. The example lists are on the long side, but each illustrates a distinct query mode (named book vs. remembered plot) and earns its space.

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

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

With no output schema, the description correctly compensates by naming the returned workId. It is nearly complete for a 3-parameter read tool, with the only real gap being the unmentioned limit/isFiction 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 coverage is 67%: query is documented ('Words to search for') while limit and isFiction carry no descriptions. The description does enrich query semantics by extending it to title, author, and thematic plot words — genuinely beyond the schema — but it never touches limit or isFiction, leaving those fields to the schema's defaults and constraints alone.

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

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

Specific verb ('Find a book') plus resource ('Siftivo catalog') and an explicit statement of the payoff: 'get the workId the other Siftivo tools take.' That return-value framing distinguishes it from siblings like get_book and get_my_book, which presumably consume a workId rather than produce one.

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

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

Gives concrete trigger examples ('add Circe to my list', 'what is Babel about') and covers both named-book and remembered-plot lookups, which is clear when-to-use context. It stops short of naming alternatives or exclusions — notably it never explains how this differs from the sibling recommend_from_description, which overlaps with the 'half-remembered plot' example.

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 readOnlyHint/openWorldHint/destructiveHint, and the description adds real value beyond them: it explains that personalized accounts have library books, hidden/avoided/passed-on titles filtered out, and that matching books carry a reason. That filtering behavior and the taste-rationale are context an agent cannot get from annotations alone.

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

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

Front-loads the core purpose, then use cases, then personalization caveats. Every sentence carries information and the ordering matches how an agent decides whether to call 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?

With no output schema, the description usefully names the categories of results and the personalization effects, though it does not describe result structure or ordering. For a single-seed read-only lookup this is nearly complete, with only structural detail about the returned lists left implicit.

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

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

Schema coverage is 100% and the schema itself already tells the agent the workId comes from search_books, get_book or a URL slug. The description only restates that the input is 'one particular book' as the seed, adding no format or constraint detail beyond the schema. 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?

Opens with a specific verb+resource ('what to read after one particular book') and enumerates the three result categories (next in series, more by author, books that read like it). This clearly separates it from recommendation siblings like recommend_from_titles and recommend_from_description, which take different seed inputs.

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

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

Gives concrete use-case phrasings ('what should I read after X', 'is there a sequel to X', 'more like X') and states the seed comes from search_books. It stops short of explicitly saying when to prefer a sibling (e.g., recommend_from_titles when you have no workId), so the routing is implied rather than spelled out.

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