VineMaker Publishing Public Catalog

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

Goes well beyond the annotations by disclosing return-field scope (public REST detail fields, publication-filtered relationships, public page/media links) and error semantics: unpublished and unknown IDs both yield not found, which prevents an agent from retrying on a presumed transient failure. The note that book content is catalog metadata with public sample links only is a substantive disclosure an agent could not infer from the 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?

Four tight sentences, front-loaded with the action and scope before the return-field and error details. No filler, and the final clarification about book content earns its place by pre-empting a plausible misunderstanding.

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 must describe returns and it does (detail fields, filtered relationships, public links). Error behavior and the public-sample limitation are also covered, leaving nothing an agent needs in order to call this single-parameter lookup correctly.

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

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

Schema description coverage is 0%, so the description carries the burden and does add real meaning: the ID is a catalog ID sourced from search_articles or a related record, which is not encoded anywhere in the schema. It does not restate the numeric pattern/format the schema enforces, but that is the schema's job.

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 ('Retrieve one published article by its catalog ID') and immediately scopes the identifier's origin to search_articles, which separates it from the search siblings and from get_author/get_book by resource type.

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 tells the agent where the required ID comes from ('obtained from search_articles or a related record'), which is the key routing decision for this family of tools. It stops short of naming when-not-to-use cases (e.g. use search_articles when you only have a title), so it is clear context rather than a full routing rule.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description still adds return-shape detail (public REST detail fields, publication-filtered relationships, page/media links) and the important not-found semantics where unpublished and unknown are indistinguishable. The closing sentence about book content and sample links is confusingly worded and only loosely tied to an author 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?

Four short sentences, front-loaded with purpose and ID provenance, then return shape, then failure behavior. The final sentence about book content/sample links is tangential and vaguely phrased, slightly diluting an otherwise tight definition.

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 usefully sketches what comes back (detail fields, filtered relationships, public links) and covers the not-found case. Given a single-parameter read tool with full annotation coverage, this is largely sufficient, with only the ambiguous closing clause as a loose end.

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 carry the burden, and it does add provenance meaning beyond the raw pattern constraint: the id is a catalog ID sourced from search_authors or a related record. It does not describe the numeric format or length constraint, but the practical semantics are covered.

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 ('Retrieve one published author by its catalog ID'), scoping it to a single published author, which cleanly separates it from the sibling search_authors that returns many. The 'published' qualifier also signals the tool's boundary.

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 tells the agent where the required ID comes from ('obtained from search_authors or a related record'), which is the key routing decision, and states that unpublished and unknown IDs both return not found. It lacks an explicit 'do not use this to search' exclusion, but the usage context is 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered; the description adds genuinely new behavior: the exact field scope returned, that relationships are publication-filtered, and that unpublished and unknown IDs both yield not found (no existence leak). It does not discuss response size, link lifetimes, or rate limits, keeping it below the top mark.

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

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

Four tight sentences, front-loaded with the action and scope, followed by return shape and error behavior. The closing sentence about content being "deliberately public sample links" is slightly dense and reads as a data-policy note, but it is not 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?

No output schema exists, so the description must sketch the return value, and it does: public REST detail fields, publication-filtered relationships, and public page/media links, plus the not-found case. The phrase "public REST detail fields" remains undefined for an agent that cannot see the REST spec, which is the main residual gap for a single-parameter fetch 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?

With one parameter at 0% schema description coverage, the description must carry the load: it identifies the argument as a catalog ID sourced from search_books or a related record, which is useful provenance. However, it does not mention the numeric string format enforced by the pattern (^[1-9][0-9]{0,18}$) or the 19-character limit, so an agent could still pass a malformed ID.

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 ("Retrieve one published book by its catalog ID") and immediately separates itself from search_books by noting the ID is obtained from that tool. The scope qualifier "published" also distinguishes it from a raw lookup of any record.

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 a clear routing rule: this tool takes an ID that came from search_books or a related record, which implicitly tells the agent to search first and fetch second. It does not explicitly state the inverse ("do not use this to search by title"), 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 already declare readOnly/idempotent/non-destructive/closed-world, and the description adds real behavior on top: public REST representation, pagination totals and next/previous links, how to continue paging, and that results include publication-filtered relationships and public links. The notable extra is the explicit 'content is never silently truncated' guarantee, which tells the agent how to interpret a large result set. It stops short of describing auth requirements or rate limits.

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

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

Front-loaded with the list/search duality and the browse condition, then the return shape and the alternative tool. The writing is dense and near-telegraphic, but each clause adds information; nothing 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?

With no output schema, the description correctly carries the return-shape burden by naming pagination totals and next/previous links, plus the pagination continuation rule. Remaining gaps are minor, such as how slug filtering interacts with q or what the sort modes mean beyond the enum.

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%, so the schema already documents q, slug, sort and author_id. The description adds meaning beyond it for page ('increment page to continue') and per_page ('large pages may require a smaller per_page'), which the schema does not explain. It says nothing extra about slug, sort or author_id, so it is not fully compensating for the remaining 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?

States a specific verb+resource ('List or search published articles') and immediately scopes it to the published collection. It also distinguishes itself from the sibling get_article by name ('Use get_article for a known ID'), so an agent can route without opening 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?

Gives the browse-vs-search condition explicitly ('Omit q to browse all records') and names the alternative tool for the lookup case. It also warns about the per_page tradeoff for large pages, so both the choice of tool and the choice of parameters are guided.

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 read-only, idempotent, non-destructive call, so safety behavior needs no restating. The description adds genuine beyond-schema context: the return is the public REST representation with pagination totals and next/previous links, and content is never silently truncated. It stops short of specifying what happens at the page ceiling (page max 10000) or what an oversized-page failure looks like.

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

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

Four dense sentences, front-loaded with the core action and the browse-vs-search switch, with no filler. The semicolon-chained return-value sentence is slightly compressed, but every clause carries information an agent can act on.

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 and no required parameters, the description correctly takes on the job of describing return shape and pagination mechanics, which it does. Only the vague "publication-filtered relationships and public links" clause and the untested page-limit behavior keep it from being fully self-sufficient.

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

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

Schema coverage is 60%, and the description compensates by explaining operational intent for the weaker parameters: q omitted means full browse, page should be incremented to continue, per_page may need lowering for large pages. slug and sort rely on their own schema descriptions, so the combined picture is complete, though the description itself adds nothing for those two.

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 ("List or search published authors") and immediately names the sibling it is not ("Use get_author for a known ID"). An agent can distinguish it from get_author and search_articles 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 explicit selection rules: omit q to browse the whole collection, use get_author when the ID is known, increment page to continue paging, and reduce per_page when a page is too large. Both the when-to-use and when-to-use-something-else conditions are covered.

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 the read-only, idempotent, non-destructive profile, and the description goes well beyond them: it discloses the REST-shaped return, pagination totals and next/previous links, how to advance ('increment page to continue'), and that results are never silently truncated. Those are non-obvious behavioral traits an agent cannot infer 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?

Front-loaded with the core verb and the browse/search distinction, then return and pagination details, then the sibling routing hint. Most sentences earn their place, but 'Includes publication-filtered relationships and public links' is vague filler that does not tell an agent anything actionable.

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 carries the burden of explaining return shape (public REST representation, pagination totals, next/previous links) and continuation behavior. What is missing is only minor: sort and slug are left entirely to the schema, and ordering semantics are not mentioned.

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%, and the description compensates for the gaps that matter most: the meaning of omitting q, the role of page in continuing pagination, and the per_page/size tradeoff. It adds little for sort, slug, and author_id, which the schema already documents, so it falls short of fully covering the remaining third.

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 opening sentence names a specific verb pair and resource ('List or search published books') and immediately separates the two modes via 'Omit q to browse all records.' It also explicitly names the sibling get_book as the choice for a known ID, so an agent can distinguish it from alternatives 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 explicit when-to-use guidance: omit q to browse, supply q to search, and use get_book instead when the ID is already known. It also states a concrete operational remedy ('large pages may require a smaller per_page'), which is the kind of conditional direction agents need.

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