Penwright — writing-craft library, guide metadata, and magazine

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 safety profile is covered and the bar is lower. The description adds real context beyond that: it is 'pure compute over public debate data' and generates 'no book text', and it discloses the shape of the result (per-debate library ids plus a union reading list).

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 input contract followed by the output and the compute-only caveat. Every clause carries information, though the dense parenthetical syntax for picks takes a second read.

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?

An output schema exists, so return-value explanation is not strictly required, and the description nonetheless summarizes the return. Inputs, requiredness and the read-only compute nature are all covered; only explicit sibling routing 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 description coverage is 100%, so the baseline is 3. The description restates the picks encoding ('A', 'B', or skip, in debate order, as a single string e.g. 'ABAB') but adds no syntax or edge-case detail beyond what the schema already documents; guide slugs are likewise already exemplified in the schema.

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

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

States a specific action (returns which library ids argue the picked side of each debate plus the union reading list) over a specific resource (a guide's debates and picks). This is clearly distinguishable from siblings like get_debate or get_guide, which surface the debate content rather than computing a reading list from picks.

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 is implied: the tool is for computing reading lists from picks over public debate data, and 'pure compute' signals it is a derived/aggregation step rather than a raw fetch. However, it never states when to prefer it over siblings (e.g., get_debate to inspect debates first, or search_library to browse works), so the agent must infer the workflow position.

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 read-only safety, and the description goes beyond them by disclosing the not-found behavior ('Returns null if not found') and the exact response shape contract. Repeating 'Read-only' is redundant but the null semantics are genuinely additive.

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 sentence, front-loaded with verb+resource, with the null behavior appended. The parenthetical contract pointer and payload enumeration add slight density but no filler sentences.

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-item getter with a full output schema, annotations, and 100% param coverage, the description supplies the essential missing bits (accepted key forms, not-found behavior). It omits any routing hint to search_answers/list_answers, which is the one remaining 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 'id' parameter is already documented as accepting 'stable id or slug'. The description's 'by id or slug' restates the schema rather than adding format, example, or validation detail, so 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 (Get) and resource (one Answer/contract v0) and enumerates the payload (question, grounded answer, citations). It doesn't explicitly name or contrast with siblings like search_answers or list_answers, though the word 'one' plus the id/slug qualifier implies single-item lookup.

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 'by id or slug' qualifier and 'Returns null if not found' tell the agent what inputs are valid, but there is no explicit when-to-use or when-not-to-use versus the sibling search/list tools. Usage must be inferred 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 establish that this is a read-only, non-destructive, closed-world operation. Beyond that, the description adds useful behavioral context by describing the structure of the returned debate: stakes, guidance, and resolvable author library IDs on either side.

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 first sentence front-loads the tool's purpose and return contents clearly. The subsequent list of 38 known slugs is long but earns its place by compensating for the lack of an enum in the schema.

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 output schema, read-only annotations, and full schema description coverage, the description provides enough context to call the tool correctly. It explains the returned entity and supplies valid slug values, which is more than sufficient for a single-required-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%, so the baseline is 3, but the description significantly adds value by listing known valid debate slugs. Since the parameter has no enum, this compensates by giving the agent concrete examples of accepted values.

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 specific verb and resource: it returns one named debate between poles argued by books on a capability guide, including stakes, guidance, and sided library IDs. It clearly describes the entity type and contents, but does not explicitly contrast itself with siblings like get_guide or get_answer.

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 is implied: retrieve a single debate by slug, and the description supplies a list of known slugs. However, it does not state when to choose this tool over alternatives such as get_guide or choose_camp, nor does it mention invalid slug behavior.

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 safety is covered structurally. The description adds real value on top: it discloses that only "live" guides are returned and that paid body/depth content is never exposed, which is the kind of scope limit annotations cannot express. It does not clarify error behavior for invalid slugs.

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 payload description, then the scope limit, then the slug inventory. Every element earns its place. Minor deduction for the trailing ellipsis, which leaves the slug list visibly truncated without saying how to retrieve the rest.

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?

An output schema exists, so return fields need not be re-explained, and annotations cover the safety profile. The description supplies the remaining essentials — which resource, which inputs, what is excluded. Only gap is the incomplete slug enumeration (23 known, 8 listed) and no guidance on unknown-slug failure.

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 single slug parameter is already documented — baseline 3. The description earns an extra point by enumerating the 23 known slugs (eight shown), which is materially richer than the schema's four generic examples and lets the agent validate input without guessing.

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 + resource ("returns one live guide's") plus an enumeration of the exact fields returned (title, subtitle, access, book count, reading time). It also draws a hard scope boundary — "card-level metadata only, never the paid body/depth content" — so an agent immediately knows this is not a content-fetch tool. No sibling shares this resource, and the named guide slugs make the target 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?

The description gives clear context for use: fetch lightweight card metadata for a known guide, and it implicitly excludes the deep paid content case. What it lacks is an explicit routing statement (e.g., which tool to call for the full guide body) or a note on handling unknown slugs. Clear context, no named alternative, so a 4.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context beyond these by clarifying what is returned (bibliographic record and, conditionally, a thesis) and flagging that not every work is profiled. This conditional return behavior is not captured in 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?

The description is a single, well-structured sentence that front-loads the action and resource. Every word earns its place, and there is no redundant or filler content.

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

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

For a simple getter with one parameter, an output schema, and safety annotations, the description is largely complete. The only notable gap is explicit differentiation from sibling tools, but the core behavior and conditional thesis handling are adequately conveyed.

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

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

Schema description coverage is 100%, with libraryId already documented as 'Library catalog id (e.g. libce6efaa49e6f0175).' The description adds no parameter-level meaning, so the baseline score of 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 ('Returns') and resource ('one writing-craft library work's bibliographic record and (when profiled) its thesis'), making the tool's function precise. It implicitly distinguishes itself from siblings get_guide, get_magazine_piece, and search_library by naming the unique content type it targets.

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 is implied by the singular resource and required libraryId parameter, but the description gives no explicit when-to-use guidance or mention of alternatives. There is no statement like 'use search_library instead when you don't have an ID' or 'use get_guide for guides.'

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 safety profile is covered. The description adds useful context by stating the content is 'ungated,' matches the human page, and which slugs are known, 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?

Two sentences carry all the essential information with no filler. The resource and returned sections are front-loaded, and the known-slug note is a compact, useful inclusion.

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 retrieval tool with an output schema and annotations, this description is complete: it identifies the resource, the content shape, the access properties, and the valid slug. Nothing required to invoke it correctly 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 only required parameter is a string slug, so the schema already defines meaning. The description adds the concrete known slug value and its hyphenated format, which is genuinely helpful beyond the schema's generic 'Magazine piece slug.'

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

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

Description opens with a specific verb ('Returns') and names the exact resource ('one published magazine piece's question, per-writer sections, and editor's coda'), distinguishing it from sibling library/guide tools by resource type. The detail 'same content the human page renders' makes the scope clear.

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

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

It is clear this tool is for fetching a single magazine piece by known slug, and the 'Known slugs (1)' line implies it should be used only when the slug is known. However, it does not explicitly state when to prefer get_guide, get_library_work, or search_library, or what to do when the slug is unknown.

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 the safety profile is covered; the description's 'Read-only' merely repeats it. The pagination/cursor behavior is disclosed, but that fact is also present in the schema, so added behavioral value is thin, though nothing is contradicted.

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; the pagination/read-only facts come first. Minor jargon ('contract v0') adds no value, but there is no waste or reordering problem.

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 an output schema present, return values need no explanation, and annotations plus full schema coverage handle safety and parameters. What remains missing is differentiation from the search_answers sibling, which for a list tool is the one gap an agent would want closed.

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% for both parameters, so limit and cursor semantics are already fully documented. The description's mention of an 'opaque cursor' echoes the schema rather than extending it, making the baseline 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 verb (List) and resource (Answers), so the agent knows it enumerates answers. However, it largely restates the name/title and adds only 'paginated with an opaque cursor. Read-only,' leaving the boundary with the sibling search_answers implicit. Purpose is understandable but not sharpened against 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?

There is no guidance on when to use this tool versus search_answers or get_answer, nor any stated prerequisites or exclusions. The reader can infer it enumerates the full set, but nothing in the text routes the agent.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the description's 'Read-only' statement repeats structured data. The only added context is 'Returns contract v0 records,' which adds little since an output schema exists and the description does not explain search ranking, coverage, or auth/rate-limit 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?

The description is three short, front-loaded sentences with no wasted words. It puts the core search behavior first, then output and safety context.

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

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

With a complete input schema, an output schema, and annotations covering safety, the description is largely sufficient for correct invocation. The main gap is sibling differentiation, which would help an agent choose between search_answers, list_answers, and search_library.

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 schema documents both the required query and the optional limit with defaults and caps. The description does not add parameter meaning beyond the schema, 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 (Search), resource (Answers), and scope (free-text query over question/answer text). It clearly separates search from sibling get_answer and list_answers, 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?

There is no explicit when-to-use guidance, no when-not-to-use guidance, and no named alternatives among the sibling tools. The free-text query scope implies search behavior, but the agent must infer when this tool is preferable to list_answers or search_library.

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 read-only and non-destructive. The description adds useful behavioral context: with no filters it returns the first page, and query/tag act as substrings that can be combined. No contradiction with annotations exists.

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 communicates the action, resource, filters, and default behavior without any filler. Every phrase earns its place.

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

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

For a simple optional-parameter search tool with a full output schema and safety annotations, the description covers the key default behavior and filter combinations well. It does not explain pagination beyond 'first page' or how an agent would request later pages, which is a minor gap.

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

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

The input schema already documents all three parameters with clear case-insensitive substring semantics, limit bounds, and defaults. The description only lightly echoes that query relates to title/author and tag to property tag, adding no meaningful syntax or format details 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 action, 'Search or list', on a clearly defined resource, Penwright's writing-craft book library, with explicit filter dimensions (title/author substring and property tag). This distinguishes it from the sibling get_* tools, which retrieve specific items rather than searching or listing.

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

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

The description implies the tool is for browsing or filtering the library, and it notes the no-filter default behavior. However, it never explicitly says when to use this tool over the sibling get_* tools or when to prefer direct retrieval, leaving the usage decision mostly to inference.

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