Chorus

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

Beyond the annotations, the description discloses the important behavioral fact that adding a person triggers no message, and explains the downstream routing difference between a person with an email (invitation plus reminders) and a name-only person (named in a group-chat reminder). That is real context the agent could not get from readOnlyHint/destructiveHint/idempotentHint. It leaves a gap on what happens when the same person is added twice, despite idempotentHint=true.

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

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

Three sentences, no padding, and the most useful fact ('Adding a person sends nothing') is well placed. But the first sentence is vague enough to waste the reader's attention, and the middle sentence carries two ideas (email invitation/reminders, and group-chat naming) that could be split for scanability.

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 two-parameter tool with full schema coverage, annotations, and no output schema, the description covers what the agent needs: what gets created and that nothing is sent. Only the duplicate-handling behavior implied by idempotentHint is unstated, which is a minor omission at this complexity.

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

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

Schema description coverage is 100%, so the schema already defines both 'book' and the name-or-name+email format for 'people', and the description largely restates that. It adds only the consequence of the name-only form (reached in a group chat), which is marginal over the schema wording.

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, 'Records who is expected to record,' is close to circular and barely identifies the resource; the actual meaning (people the book is waiting on) only becomes clear from the title and the following clause about email addresses. Once decoded, the verb+resource is specific enough, but the first read is ambiguous and could be misread as recording a response rather than adding a person.

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 'Adding a person sends nothing' implicitly tells the agent this is not the dispatch step and steers it away from send_it_out / chase_the_missing, which is a genuine usage signal. However, no sibling is named and the description never says when to use this versus chase_the_missing or close_collecting, so the routing must be inferred.

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 establish that this is a read-only, idempotent, non-destructive operation. The description adds substantial behavioral context by enumerating the returned status fields, including outstanding participants, submission counts, collection deadlines, and next action dates.

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

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

The description is front-loaded with the core return concept and then enumerates relevant status fields. It is a long single sentence, but the length is largely justified because there is no output schema to document return values.

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 status tool with one fully documented parameter and no output schema, the description covers the important return information thoroughly. It explains who has responded, what has been submitted, who is outstanding, remaining collection time, and upcoming action dates.

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 single parameter, book, has complete schema description coverage, so the schema already explains that it is the book's handle. The description does not add any further meaning about the parameter beyond that 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?

The description clearly states that the tool returns a book's participation status, including who has recorded, what has been submitted, who is outstanding, and timing details. It is specific about the resource and returned information, but it does not explicitly distinguish itself from siblings such as order_status or find_my_book.

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 returned status content, so an agent can infer this is the tool for checking a book's progress and deadlines. However, there is no explicit when-to-use guidance, no when-not-to-use guidance, and no naming of alternatives such as chase_the_missing or close_collecting.

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 mutation, idempotency, and non-destructiveness, so the description's key added value is 'Nobody is told about a change' — a genuine side-effect disclosure about notifications that no structured field carries. It does not clarify whether omitted fields are left untouched, which is the remaining behavioral gap.

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

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

A single front-loaded sentence that lists the affected settings efficiently, followed by a short side-effect note. No filler and no repetition of the title.

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 seven-parameter mutation tool with no output schema, the definition omits whether partial updates preserve existing values and who is permitted to call it, both of which affect correct invocation. The no-notification note and the enumerations cover much of the ground, but the update semantics gap keeps it at minimum-viable-plus.

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 all seven parameters are already documented, and the description's phrasing ('which one the button offers first', 'offered to chip in towards the printed book') largely restates those schema descriptions. The baseline 3 is appropriate; it adds nuance but no syntax or constraints beyond the schema.

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

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

The description uses a specific verb ('Changes the settings') and enumerates the concrete settings affected: closing day, questions, allowed media, button order, and chip-in. It is clear what the tool mutates, though it does not explicitly separate itself from siblings like close_collecting or reopen_collecting that touch the same closing-date concept.

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 only implied through the enumerated settings; there is no statement of when to prefer this over close_collecting (for the closing date alone) or set_style. The agent must infer routing from the field list rather than being told.

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 annotations already declaring openWorldHint=true and idempotentHint=false, the description still adds real value: it discloses that emails go out externally, that only people with an address are emailed, and that hard caps exist (one per day, three total, never after an opt-out). What it does not cover is the empty case — what happens when nobody is missing — or any failure 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 sentences, front-loaded with the action and followed by the constraints, with no filler about the tool's importance. The phrase 'ready for the group chat and ready for one person' is slightly redundant, which keeps it from a 5.

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 two-parameter mutation with no output schema, the description covers the action, the external side effect, the recipient filter, the returned message, and the rate limits — enough for an agent to call it correctly. The main omission is the no-op case when everyone has already recorded.

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 already defines both parameters, making 3 the baseline. The description still adds meaning: 'emails a reminder to the ones with an address' clarifies the recipient filter behind `book`, and 'hands back a message ... ready for the group chat and ready for one person' explains the payload returned in the no-send mode that `also_email` controls.

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 chain: identify who hasn't recorded, email the ones with an address, and return a message naming them. That is far more specific than the title alone and clearly separates it from siblings like send_it_out or read_the_messages, which do not compute a missing-participant set. It stops short of naming any sibling explicitly, so it lands at 4 rather than 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?

Usage is implied by 'who is still out' — the agent can infer this is for chasing non-responders on a given book. There is no explicit statement of when not to use it, nor any pointer to an alternative tool for a different kind of reminder. The rate-limit sentences are behavioral constraints, not usage 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 only declare the flags (non-readOnly, non-destructive, non-idempotent); the description adds real substance by clarifying that nothing is deleted, the book is not finished, and the state is reversible. It does not address what happens on a repeated call, which the non-idempotent hint makes relevant.

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 its result, then the safety/reversibility caveat. No filler and no repetition.

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

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

For a one-parameter, no-output-schema tool, the description covers the action, the return (counts plus gift link), and the reversibility guarantee. Only the repeated-invocation behavior is left unstated.

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?

Single 'book' handle parameter is fully documented in the schema (100% coverage), so the schema carries the load. The description adds no extra meaning about the parameter, which is acceptable at this coverage level.

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 ('stops new messages arriving') and adds what is returned ('final counts with the gift link'). It also hints at the reverse operation ('it can be reopened'), though it never names the reopen_collecting sibling outright.

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: call this when you want to stop accepting new messages but keep the book alive. The existence of a reverse action is signalled ('it can be reopened'), but no explicit when-to-use or when-not guidance and no named alternative tool.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, and the description supplies the reason: the first call sends an actual email to an external address and returns nothing. That is useful context beyond the annotations. It doesn't cover repeat-call behavior (does calling again send another code?), code expiry, 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?

Three short sentences, front-loaded with the primary case and then the code case, ending with the security rationale. Nothing is padded, though the last sentence is reassurance rather than operational instruction.

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 two-parameter tool with no output schema, the description covers the full flow, the side effect, and what comes back (books with handles). Only edge cases — expired codes, repeated requests — are left unstated.

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 documents both parameters, including that omitting code causes Chorus to email one. The description restates that conditional behavior rather than adding format details, so it sits at the baseline for a fully documented 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 two-phase operation with concrete inputs and outputs: email alone triggers a six-digit code email and returns nothing about books; email plus code returns every book on the account with its handle. This is distinguishable from siblings like their_own_link and get_links, which imply different recovery paths.

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 makes the call sequence clear: call without code to trigger the email, call again with the code to get handles. It also states a constraint that shapes usage — possession of the mailbox is the proof, so addresses can't be guessed. It stops short of explicitly naming sibling alternatives for handle recovery.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful output context by listing the kind of links and message returned, but it does not explain link expiry, permissions, or why the 'link that plays every message straight through' differs from the collecting link.

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 definition is a single front-loaded sentence that states the return content without filler. It is concise, though the phrase 'the link that plays every message straight through' is somewhat vague and could be sharper.

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 read tool with no output schema, the description does list the three return artifacts, which partly compensates for the missing output schema. However, it leaves ambiguity about what each link does and provides no usage context, so it is adequate but not fully complete.

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

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

Schema description coverage is 100%, so the single 'book' parameter is already documented in the schema as 'The book’s handle.' The description adds no parameter-level meaning beyond that, which is appropriate given the high schema coverage.

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

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

The description uses a specific verb ('Returns') and names the three artifacts the tool produces: a contributor-forwarding link, a playback link, and a pasteable organiser message. It is clear what the tool does, but it does not distinguish it from siblings such as their_own_link or send_it_out.

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 no explicit when-to-use guidance, no conditions for choosing this tool over alternatives, and no prerequisites. Usage is only implied by the stated outputs, leaving the agent to infer when to call it.

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

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

The annotations already cover read-only, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description adds valuable context about the returned data—style attributes, meanings, print-rule limits, and the people who have pages—though it remains vague about how the optional 'person' parameter affects the response.

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 sentence that front-loads the core action, but it is somewhat wordy and includes vague phrases like 'what each part means' and 'the limits the print rules keep'. A tighter structure would improve clarity.

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 low-complexity read tool with no output schema, the description adequately conveys what the style file contains. It still leaves minor ambiguity about how the optional 'person' parameter changes the output scope, but the schema covers parameter details sufficiently.

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 fully documents both parameters. The description’s mention of 'a person’s page' hints that the 'person' parameter filters to that person’s style, but adds no meaning beyond what the schema already provides.

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

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

The description clearly states the verb 'Reads' and the resource 'the book’s style file', and it enumerates the content returned (size, place, typeface, colour, alignment, meanings, limits, people). This distinguishes it from the write-oriented sibling set_style, though it does not explicitly name 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 alternatives like set_style or preview_pages, nor any prerequisites or exclusion conditions. The agent must infer its role as the read counterpart to set_style.

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, openWorldHint=true, idempotentHint=false, so the write/external profile is covered. The description adds genuinely new context: pricing and card capture happen on Stripe's page, keepsake also collects a postal address, and the tool itself never handles a card or names a price — a meaningful scope boundary for an agent deciding what it can promise.

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 return value, then the option taxonomy, then the Stripe scope boundary. No filler, and each sentence adds a distinct fact.

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 only two required params and no output schema, the definition covers what the agent needs: what comes back (a payment link), where payment happens, and what the tool will not do. Minor gap: it does not say whether repeated calls yield separate links, though idempotentHint=false hints at that.

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 already defines 'book' as the handle and lists the three option values with the keepsake posting note. The description restates those meanings rather than adding syntax, defaults, or validation detail, so the baseline 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?

States a specific verb and resource — 'Returns a payment link' — and enumerates the three option values (voices, book, keepsake), with keepsake clarified as the printed hardcover. That is enough to separate it from siblings like order_status or get_links 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?

The implicit trigger is clear: call this when someone has chosen one of the three options and needs to pay. But it never says when NOT to use it or points to order_status for checking an existing order, so routing between siblings is left to inference.

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 (readOnlyHint, idempotentHint, non-destructive, closed-world), so the description's added value is the return payload, which it does disclose: payment state, purchased option, print stage, and tracking. Since there is no output schema, this prose is the agent's only view of what comes back, and it conveys the categories, though not field names. The phrase 'on a printed one' also usefully signals that the print-stage data is conditional.

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 the primary answer (paid or not) before the secondary print-stage detail. The trailing clause ('on a printed one the stage the printer is at with the tracking') is slightly tangled but not 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?

For a one-parameter read-only status lookup the description is close to sufficient: safety is covered by annotations and return categories are stated. The remaining gap is ambiguity against book_status and the lack of any field-level shape for the response, which matters because no output schema exists.

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?

There is a single required parameter ('book', the book's handle) with 100% schema description coverage, so the schema already carries the semantics. The description adds nothing about how the handle is obtained or formatted; baseline 3 applies when the schema does the heavy lifting.

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 ('Returns') plus the exact resource contents: paid status, which option was bought, the printer's stage, and tracking. An agent knows what it gets back. It loses the top score because it never distinguishes itself from the closely named sibling book_status, leaving the agent to guess which status tool covers which question.

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 output only; there is no when-to-use, when-not-to-use, or named alternative. With book_status in the sibling list, the absence of any routing guidance is a real selection hazard rather than a minor omission.

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 read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds real value beyond them: the output is a print-faithful preview generated by the printer's own layout code, and the no-argument case yields the first message. It omits any note on image count, size, or delivery format.

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 the main verb first and a colon-separated enumeration of selection modes; no filler. Slightly dense prose but every clause carries 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 and a tool whose return value is images, the description never says what the pictures arrive as (URLs, embedded data, count per call) or whether the four-page cap in the schema is enforced server-side. Adequate for correct invocation, but incomplete for interpreting results.

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 baseline is 3. The description nevertheless contributes new meaning the schema lacks: the precedence rules among pages, person, and the default first-message behavior, plus confirmation that each page yields its containing spread.

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 ('Returns pictures of the spreads the book prints') and adds a strong qualifier: the rendering comes from the same code that builds the printer's file. That distinguishes it from any sibling (order, send_it_out, book_status) 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 spells out the three selection modes and, crucially, the fallback ('the first message when neither is given'), which tells the agent it can call with only the required book parameter. It does not explicitly say when to prefer this over reviewing an order or status, so it falls short of a full when/when-not statement.

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, idempotent, non-destructive and closed-world behavior, so the bar is lower, and the description still adds real context: non-text messages are transcribed only on tiers that include words, and the tool reports failure explicitly rather than returning a partial answer. That degradation behavior is not captured anywhere in the structured fields. It stops short of disclosing volume or pagination for what is claimed to be an every-message return.

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, but the phrasing is oblique: "reads back whatever was paid" and "the tier that includes the words" force the reader to decode rather than parse. Front-loading the return contents is good; the editorialized register costs clarity without adding information.

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

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

For a single-parameter read tool with no output schema, the description covers the essentials: what comes back, whose it is, and how non-text content is handled when unsupported. The only meaningful omission is the absence of any stated bound or ordering for a return set described as "every message."

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 the single required parameter, so the schema already explains it. The description adds nothing about the book handle's format, source, or how to obtain one (a sibling like find_my_book presumably supplies it), so it neither compensates nor detracts.

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 first sentence states a specific verb and resource: it returns every message, with attribution and body content. That is concrete and not a restatement of the title. However, it never clarifies the domain vocabulary ("book", "handle") and draws no boundary against siblings such as preview_pages or book_status, which an agent could plausibly confuse with reading content.

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 and no named alternative among the eighteen siblings. The only implicit usage signal is the tier caveat about voice/video transcription, which tells the agent what to expect rather than when to choose this tool over preview_pages or book_status.

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=false, idempotentHint=false and openWorldHint=false, so the mutation and safety profile is covered structurally. The description adds real value beyond that by noting the link is returned for re-sending, but it stays silent on what happens to already-collected messages, whether the old link is invalidated, and what occurs when closes_on is omitted.

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, front-loaded with the action and the two entry states, ending with the return value. No sentence is wasted.

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 flags that a collecting link comes back, which an agent needs. However, for a state-changing tool it omits the consequences of reopening (message handling, prior link validity) and the behavior when the optional closing date is left out.

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 both 'book' (handle) and 'closes_on' (date format example) are already documented in structured data. The description adds nothing beyond the schema about the optionality or effect of closes_on — only the title hints at 'a new closing date if there is one'. 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 (reopens) and resource (a book), plus the two triggering states — 'closed or whose date ran out' — and adds that it returns the collecting link. This implicitly distinguishes it from close_collecting, though it never names the sibling outright.

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 condition for use is explicit: a book that was closed or whose date expired. There is no exclusion or named alternative, but the trigger state is concrete enough that an agent can act without inference.

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 establish that this is a non-destructive but non-read-only, non-idempotent, closed-world operation. The description adds meaningful behavior beyond that: email addresses and phone numbers are removed before the note is kept, and it explicitly says nothing on any book is changed and nobody is emailed.

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

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

The description is two tight sentences with no wasted wording. The core action and scope come first, followed by the important privacy and safety guarantees.

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 feedback-submission tool with fully documented parameters and no output schema, the description covers purpose, triggering situations, privacy handling, and the fact that no book state changes. An agent has enough information to decide when and how 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?

Schema description coverage is 100%, so all five parameters are already documented in the input schema. The description reinforces the note's purpose and brevity but does not add syntax or constraints beyond what the schema provides.

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

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

The description uses a specific verb and resource: it sends a short feedback note to the people who make Chorus. It clearly scopes the content to failed tools, unexpected results, uncovered requests, or unclear descriptions, which distinguishes it from all the book-related sibling 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?

It gives clear when-to-use guidance by listing the situations that warrant feedback: a tool failed, returned something unexpected, a request no tool covers, or a description was unclear. It does not explicitly say when not to use it or name an alternative, but for a feedback channel there is no obvious sibling alternative.

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

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

Annotations already declare non-read-only, idempotent, open-world, non-destructive, so the bar is lower; the description still adds real value by disclosing the per-caller daily email limit and the no-duplicate-send guarantee, plus the fact that the return value is a usable link/tap rather than a status. It stops short of saying what happens on failure or what the returned tap 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?

A single compact sentence that front-loads the two outcomes (email sent, tap returned) and then qualifies them. No filler, no repetition of the title.

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 two-parameter tool with no output schema, the description covers the side effect, the idempotency guarantee, the rate limit, and what comes back. Only error/edge behavior and the shape of the returned tap are left unstated.

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 suppress-email behavior that the also_email parameter description already carries and adds nothing about the book handle beyond what the schema says.

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: emails the invitation to every person with an address, and returns a tappable link for WhatsApp/text/mail. That distinguishes it from siblings like add_people or chase_the_missing, though the phrase 'the tap' is jargon-heavy and the sentence is long enough that the core action isn't as crisp as it could be.

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 situational context — use it for the family group and for anyone with no address — and notes that suppress-email behavior exists, but it never names an alternative tool or spells out the condition that would send an agent to preview_pages or chase_the_missing instead. Usage is implied rather than 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=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered; the description adds real value beyond that by disclosing that the call may be partly refused (with a reason) and that print rules can override a requested value (with a reason). It also states the response includes rendered page images, which no structured field conveys. Minor gap: it does not say what reset does to previously applied per-person overrides.

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 response-contract sentence is front-loaded and earns its place, and the two JSON examples are dense but useful. However, the framing sentence for the second example ("A smaller code on the right, for the voice note only") is confusing and obscures what the example actually demonstrates, and the examples are not labelled by purpose, so the reader must decode them.

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 correctly fills that gap by describing all four return elements (applied values, print-rule overrides with reasons, refusals with reasons, rendered page images). For a three-parameter mutation tool with full annotation coverage and full schema coverage, the remaining omission is only the exhaustive set of valid paths.

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 nested change object's path field carries no format description in the schema and the description supplies the missing DSL semantics with concrete examples (codes.size_mm, words.size_pt, heading.italic, ink, margins_mm.top) and shows how person scopes a change to one person's pages. The list is illustrative ("such as") rather than exhaustive, so an agent still has to guess at valid parts.

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?

"Changes any line of the book's style file, for every page or for one person" gives a specific verb and resource plus the two scoping modes, which is enough to tell it apart from the read-side sibling get_style and from preview_pages. It stops short of explicitly naming those siblings, so it is clear but not maximally differentiated.

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 explains what can be changed and that reset returns to the standard page, but never states when to use this versus get_style (read the current style) or preview_pages (see the result), nor any prerequisite such as needing the book handle first. Usage is only implied by the field examples.

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 only say not read-only, not idempotent, not destructive. The description goes well beyond: gathering is free, contributors need no app or account, the book is created immediately, the link is emailed to the organiser and again on every response, and the book transfers into their account on sign-in or by opening keep_link. That is exactly the operational context an agent needs for a non-idempotent create.

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 action and the return values, then prerequisites and follow-on behavior. There is mild redundancy between 'returns its handle and the single link' and 'the link comes back,' and the trailing email paragraph is dense, but nothing is wasted.

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?

Covers creation flow, prerequisites, and return values for a parameter-heavy tool with no output schema. It does not say what the returned handle is used for (e.g., feeding book_status or change_the_book later), which is a meaningful gap for an agent chaining calls, but the core is complete.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters in detail, including code, steps, subject_name and questions. The description only restates the organiser_email semantics and the subject_name/title constraint, adding little beyond the structured fields; 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?

Uses a specific verb and resource ('Starts a book of voice, video and written messages') and states the two return values (handle and the single forwardable link). Among siblings like change_the_book, find_my_book, preview_pages, this is unambiguously the creation tool.

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 clear context for when this is the right call: for one person, a couple, or nobody in particular via a title, and notes the organiser_email requirement 'unless they are signed in through the connector.' It never names an explicit alternative for modifying an existing book (change_the_book), so it falls short of full 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, idempotentHint, destructiveHint=false and closed-world scope, so safety is covered. The description adds genuinely new behavioral context: the tool fails for three specific book types and returns a single-person link rather than a group one. It does not say what the failure looks like (error vs. null) or anything about link lifetime, which keeps it from a 5.

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

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

Three short sentences, front-loaded with what is returned before the refusal conditions. Every sentence carries information about the return value, exclusions, or the alternative. Minor awkwardness ('an as they grow book') slightly hurts readability but not substance.

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 link getter with annotations covering safety and no output schema, the description covers what is returned, who it is for, and when it fails. The remaining gap is what the returned link looks like or whether it expires, which is minor for this complexity level.

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?

There is one parameter with 100% schema description coverage ('The book's handle'), so the schema already carries parameter meaning. The description adds no syntax, handle format, or lookup guidance beyond that. Baseline 3 is appropriate for full schema coverage with no extra param insight.

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 return value (the second link) and explains what that link does: it puts questions to the person the book is about regarding their own life. It also distinguishes it from the 'collecting link' used for group chats, which separates it from the family of link-related siblings. The phrase 'second link' is mildly jargon-dependent, and it never explicitly names the get_links sibling, keeping it just 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 gives concrete when-not conditions: refuses on a memorial, a new baby book, and an 'as they grow' book, where the person cannot answer. It also states the alternative for the group-chat case, pointing to the collecting link. There is no explicit naming of the sibling tool that returns the collecting link, so the routing is conceptual rather than literal.

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