voicehook

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

Annotations already cover mutability and open-world behavior, and the description adds genuinely new context: the line is appended, timestamped, visible on the call page, and never spoken, while context/faq remain hidden from the page. It does not mention that repeated calls create duplicate lines (consistent with idempotentHint=false) or the permission/session prerequisites.

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

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

Three short sentences, front-loaded with the action and the visible result, followed by the key behavioral constraint and the hidden-field note. No filler; the fragment 'Never spoken.' earns its place as the main routing signal.

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?

All five parameters are documented in-schema, an output schema exists, and annotations cover the safety profile, so the description only needs to add the visible/hidden distinction, which it does. The remaining gap is the session prerequisite ('the `session` value returned by join') being left entirely to the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only re-frames `context` and `faq` as 'hidden background of this line for the voicebot', which is essentially what the schema already documents; no extra syntax, format, or selection guidance is added.

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 ('Append one line ... to the activity feed on the call page') plus a hard length constraint (3-8 words). It implicitly separates itself from the speaking siblings via 'Never spoken', but never names `say` or `helper_activity`, so the differentiation is inferred rather than explicit.

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 'Never spoken' and 'shown as a timestamped line' phrasing implies this is for silent page log entries rather than spoken output, which does route the agent away from `say`. However there is no explicit when-to-use/when-not statement, no mention that a session from `join` must exist, and no guidance on choosing this over `helper_activity`.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses behavior richly: additive-only semantics, account scoping to the paying account, hard limits (20 entries per invocation, 100 per call, 50 chars), immediate-effect timing, and the 409 guest-call failure mode. It even enumerates the return payload.

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 purpose, followed by constraints, timing, error behavior, and return shape — each sentence carries information. It is dense and slightly run-on, and restating return fields is mildly redundant given the output schema, but there is little true filler.

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

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

For a mutation tool with an output schema, the description covers everything an agent needs: limits, timing of effect, account scope, failure mode (409 for guest calls), and the return structure. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: `fixes` is a {wrong, right} mishearing/correction pair and, importantly, `right` is also appended to terms. That side-effect is not derivable from the schema and would change how an agent constructs input.

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 opens with a concrete verb+resource: 'Teach the call's speech recognition words it keeps mishearing', immediately clarified with examples (product names, people, jargon). No sibling tool overlaps this function, so an agent can select it unambiguously.

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

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

Usage context is clear (correct recurring mishearing errors during a call) and scope is spelled out: add-only, never deletes, and the list is not returned here but managed on the account page. No explicit alternative tool is named, but none exists among the siblings, so the omission is minor.

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?

Goes far beyond annotations: explains that account rules govern opt-in, reasons, quiet hours, per-day limits and budget, that refusals return {status: refused, why}, and that the call continues in the background and is billed at end. It also distinguishes blocking-until-answer from background continuation, which is exactly the behavioral context an agent needs for an openWorld, non-idempotent action.

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

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

Front-loaded with the core action and trigger, then return statuses. Dense but nearly every clause carries information; the return-status enumeration is slightly compressed but 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?

Even though an output schema exists, the description explains the return contract (answered/no_answer/busy/failed/insufficient, refused with why) and the async billing model, so an agent knows both what it gets back and what continues afterward. Complete for a call-placing 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%, but the description still adds value by stating 'You never pass a number', enumerating reason values (done | blocked | decision), and clarifying that message (max 200 chars) 'opens the call'. It mostly echoes the schema's field docs, keeping it just below a 5.

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 ('Phone the human who owns this call on their own confirmed phone number') and clarifies the 'you never pass a number' constraint that separates it from a generic dialer. An agent can distinguish it from notify_me/say/activity without opening the schema.

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

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

Gives clear when-to-use triggers ('when a long task is done, you are stuck, or you need a decision and they are not on the call page'). It does not explicitly name when NOT to use it or point to the closest alternative (notify_me), so it falls short of a 5.

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

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

Annotations only supply safety hints (readOnlyHint=false, openWorldHint=true); the description adds substantial behavior beyond them: return fields, 30-minute expiry, 429 and 410 error semantics, the 200 s/50 s join wait limits, and the repeatability of join. This is unusually rich disclosure for a mutating, open-world 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?

Front-loaded with purpose and the lang hint before the dense field/error/workflow block. It is long and reads as a single paragraph, but nearly every sentence carries needed operational detail, so there is little waste.

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 call-initiating tool with an output schema, the description still supplies the workflow contract, expiry and timeout semantics, error codes, and the share_text prerequisite. Nothing an agent needs to call this correctly and then route into join/next 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 75% and the schema already documents name, solo, and lang in detail. The description's mention of lang ('de or en, default de') largely restates the schema, and it adds nothing for name, solo, or mode, so it does not meaningfully exceed the baseline.

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

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

States a specific verb+resource ('Start a new voicehook.ai voice call') and its default behavior. It also references the follow-on sibling tools join and next, so an agent can distinguish this from join/next/say/leave without opening schemas.

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 'Hard rule' section gives explicit sequencing: show share_text first, then call join immediately, repeat until `session`, and continue with next in a loop. It also names the background-job-over-HTTPS-bridge alternative, so both when-to-use and alternatives are spelled out.

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

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

Beyond the annotations (which already declare a write with destructiveHint=true), the description discloses the error paths (422 for over-long questions or invalid done fields, 403 for auto-detected decisions, `warnings` rather than an error when context/faq are thin), the card lifetime rules, and that the answer arrives asynchronously as a `next` event with a full verdict vocabulary. One nuance conflicts with the schema, however: the description says faq is 'shown below it as questions and answers' while the schema calls it 'hidden, for the voicebot'.

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

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

The core purpose and the say-comparison are front-loaded, which is right, but the body is one dense run-on block of semicolon-joined clauses with no headings or bullets, and it spends a long stretch enumerating the full `next` event payload that structured output already covers. It is information-rich but would be markedly easier to scan if split into Create / Edit / Done / Response sections.

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 17-parameter tool with two card modes, an async answer channel, and several documented error codes, nothing an agent needs to call it correctly is missing: limits, required-vs-optional behavior, the edit/delete path, and the reply event shape are all present. The presence of an output schema makes the verbose return-value section redundant rather than necessary, but it does not leave gaps.

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; the description nonetheless adds real meaning for a few fields, e.g. that omitting options yields Yes/No buttons, that context lines starting with '- ' render as bullets, and that no_question must be passed alone. Several limits (2-3 options, 40 chars, 0-based recommend, 160 chars) restate the schema rather than extend it, which caps this at 4.

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 opens with a concrete verb and resource ('Put a question for the person on the call's Decision Board') and immediately names the sibling it is not: a question 'spoken via say leaves no button and no decision event.' It also distinguishes the card_type=done variant ('completion report instead of a question'), so an agent can separate three modes without opening a schema.

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

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

It states the intended scope explicitly ('Meant for every question the person decides: yes/no, A/B, an approval, picking a value') and gives the exclusion that matters (use say if you only want speech, because it produces no decision event). It also routes the two other modes: id plus new fields to change, id plus delete true to remove, and card_type done for finished work.

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, openWorld and non-destructive, so there is little safety burden left; the description still adds real context beyond them, notably the 503 error semantics ('voicebot not (yet) in the call') and the meaning of derived fields like 'mine' (asked by this session or one of its helpers) and 'auto'. It does not mention pagination 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?

Purpose and scope are front-loaded in the first clauses, which is good, but the bulk of the text is a long enumeration of returned fields (id, number, question, options, recommend, agent, from, sender, state, at, age_s, mine, context, verdict, option, text, by, decided_age_s) that largely restates the output schema. Much of that verbosity does not earn its place given an output schema exists.

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?

Because an output schema exists, the return-shape prose is not strictly needed, and the remaining essentials — scope, ordering across the three result groups, and the 503 failure mode — are all present. Coverage is solid; only explicit usage routing against siblings 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?

With a single parameter at 100% schema description coverage, the schema already explains that session is 'the `session` value returned by join'. The description adds nothing about the parameter itself, so the baseline 3 applies.

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

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

The opening clause gives a specific verb and resource with scope: 'Lists every OPEN decision on the call's Decision Board, from all agents in the call and their helper sessions' plus ordering ('oldest number first'). It also clarifies the audiences (main agent, helper sessions). It stops short of naming a sibling it is distinct from, so it falls one notch below 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?

Usage is only implied by the phrase 'read-only overview for the main agent' and by the read-only annotations; there is no explicit when-to-use statement, no condition selecting it over decide/helper_decide/status, and no exclusions. An agent can infer it is the read path, but nothing is 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 declare readOnly=false, idempotent=false, openWorld=true, but say nothing about what the write produces. The description fills that gap: the exact feed line format, that it is silently logged rather than spoken, that `context` and `faq` stay hidden from the page, and that the call returns the line. It omits any mention of credential/permission failure behavior, which is the only notable 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?

Three short sentences, front-loaded with the precondition and output format, with no filler. The middle sentence duplicates schema wording on context/faq, which is the only wasteful element.

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 6-parameter mutation tool with an output schema and full schema coverage, the description covers the who/what/how plus the non-obvious hidden-field semantics, so an agent can call it correctly. Only the `goal` parameter's interaction with this tool (schema mentions 'helpers: no inheriting') goes unmentioned in the description.

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 every parameter is already documented in the schema, including that `context` and `faq` are hidden voicebot background and that `text` is 3-8 words. The description largely restates those facts ('context and faq: hidden background of this line for the voicebot'), adding little new meaning, notably skipping the `goal` parameter entirely. 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 concrete verb+resource (appends one line to the call's activity feed) and pins the exact rendering format 'Helper <label>: <helper_name>: <text>'. The precondition 'for a helper session that is not in the call' distinguishes it from the sibling `activity`/`say` tools, which operate for the in-call agent.

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 situational precondition (helper session, not in the call) and signals the line is 'never spoken verbatim', which implicitly rules out using this to talk to the participant. It does not explicitly name the alternative to use for spoken output (e.g. `say`), so the routing guidance stops just short of complete.

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?

Adds real behavior beyond the annotations: the credential's scope is limited to helper_* tools and /api/activity/relay*, it expires when the call ends, and rotate=true invalidates every earlier helper credential for this call. That rotate semantics is exactly the kind of side effect annotations (destructiveHint=false, idempotentHint=false) don't convey.

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 dense paragraph front-loads the return value and its audience, then layers label format, rotate semantics, and scope limits. Every clause carries information an agent needs; nothing is padded.

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 an output schema exists, return values are covered, yet the description still adds the lifetime ('ends with the call') and the tool-scope restriction, which are critical to correct invocation. Complete enough that an agent could use the credential safely.

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

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

Schema coverage is 100%, so the baseline is 3, but the description still enriches parameters: label is the helper's machine name (max 22 chars) rendered as 'Helper <label>: <helper_name>', and rotate's invalidation effect is spelled out beyond the schema's terse 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?

States a specific verb+resource ('returns a helper credential token') and immediately enumerates the return payload (url, expires_in). It also distinguishes itself from siblings by describing the helper's role (add status/decisions/activity without joining, no voice, no chip) versus join/say.

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?

Clearly frames the use case ('other sessions working for the same person add their own status board... without joining') and the exclusions ('never for say or join'). It stops short of naming a competing sibling to pick instead, so the when-to-use-vs-alternative routing is implied rather than explicit.

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

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

Beyond the annotations, it discloses permissions and side effects: only own questions can be changed or deleted, otherwise 403; duplicate unseen titles update the existing card; missing context/faq produces warnings; and card_type done shows only a Seen button. These are substantial behavioral details not already 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 purpose is front-loaded, but the description is a dense run-on covering many clauses, and it spends space explaining return values despite the presence of an output schema. It is information-rich but not well structured for quick scanning.

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 complex helper tool with 18 parameters, the description covers the core workflow, permissions, limits, card types, update behavior, and answer routing. Anything not covered in prose is fully documented in the input schema, and an output schema exists for return values.

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 18 parameters. The description adds some semantic meaning for context, faq, and card_type done, but it repeats many schema limits and omits goal, ttl_s, delete, and no_question entirely, so the baseline 3 is appropriate.

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

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

The description names a specific verb and resource: placing a question on the Decision Board from a helper session. It distinguishes itself from decide by saying 'Same fields and limits as decide' and from the main agent's next by routing answers through helper_next.

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 a clear when condition ('For a helper session that is not in the call') and covers change/delete and card_type done. The alternative routing to helper_next is explicit, though it does not spell out a full 'use decide instead when...' exclusion.

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, openWorld, idempotent=false, and destructive=false; the description adds substantial behavioral detail beyond that. It discloses event structures, waiting up to timeout when none is there, a 50-event retention cap, and call-end expiration, giving the agent a clear lifecycle model.

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 purpose is front-loaded in the first clause, but the entire description is one long run-on sentence with nested parentheticals and inline event schemas. The detail earns its place, yet the lack of structure hurts scannability.

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 an output schema and annotated safety profile, the description covers the key event types, wait behavior, and retention limits. It leaves gaps such as event ordering or whether returned events are consumed, which keeps it from 5.

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 repeats the timeout range and the need for the same credential and helper_name, but adds no syntax, format, or failure semantics 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?

States a specific verb ('returns') and resource (answers to its own questions and related events) for a helper session not in the call. It names helper_decide in the question_check context, which helps distinguish retrieval from decision submission, though it does not explicitly contrast with helper_activity or helper_status.

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

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

Provides clear context: use for a helper session that is not in the call, and mentions helper_decide for answering question_check events. It lacks explicit when-not-to-use guidance or alternative routing among sibling retrieval tools, so it is not a 5.

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

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

Goes well beyond the annotations: discloses the visible sender string format 'Helper <label>: <helper_name>', that images return ok only after a call page loads them (with a shown count) and otherwise error with a stated reason, rate limits (10 images/minute), size caps, and that the server self-confirms pdf/csv/md. Annotations only say non-read-only, open-world and non-idempotent, so this detail is 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?

Purpose comes first and every sentence carries operational detail. The kind-by-kind constraint dump makes it a dense single paragraph that is slower to scan than a short bulleted structure would be, but there is little outright 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?

Covers the practical picture for a 10-parameter mutation tool: what appears on the page, sender labeling, per-kind payload rules, failure modes and limits. With an output schema present and required parameters documented, nothing an agent needs to call 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 already 90%, yet the description still adds semantics the schema lacks: link must contain exactly one http(s) URL, image must be SVG or base64 raster and never a URL, image requires context, and the per-kind meaning of `text`. The generous size limits are useful reinforcement rather than new information.

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 action and resource: places a card on the person's call page from a helper session that is not in the call, and explicitly notes it is never spoken. The scoping clause 'not in the call' separates it from the related 'show' tool, though the phrasing is embedded mid-sentence rather than front-loaded.

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 opening condition ('For a helper session that is not in the call') tells the agent when this tool applies and implicitly when the plain 'show' tool does instead. It references 'show' for shared limits but does not explicitly say to use 'show' when the helper is in the call, so no exclusions are spelled out.

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

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

Adds substantial behavior beyond the annotations: empty doing/open/done removes the helper's board (the destructive effect behind destructiveHint=true), meta is hidden background for the voicebot and never shown on the page, missing context/faq produces `warnings` rather than an error, and helpers do not inherit goals. These are exactly the operational details an agent needs and are not present in the annotation flags.

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 identity/scope sentence, then limits, then meta, then removal and return behavior. It is dense and sentence-long in places, but every clause carries operational information; minor readability cost without waste.

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, the description still covers the parts schemas cannot: display placement, page-vs-voicebot visibility, warning-not-error behavior, and the destructive empty-payload case. Nothing material for correct invocation is missing for a helper-scoped board mutation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the `meta` entries are explicitly invisible to the page and consumed by the voicebot, and the warnings coupling with context/faq is only stated here. It also clarifies the empty-value removal semantics for doing/open/done beyond the schema's max-length notes.

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 ('sets its own status board on the call page') plus the exact rendering ('Helper <label>: <helper_name>' below the main agent). It explicitly separates itself from the sibling `status` by noting the main agent's board stays unchanged and that limits match `status`, so an agent can differentiate without opening schemas.

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 applicability condition ('For a helper session that is not in the call') and implies the alternative (`status`) by reference to its limits. It does not explicitly state when NOT to use it or name which sibling to pick for a non-helper session, so it falls short of full when/when-not/alternatives 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?

The description discloses extensive behavior beyond annotations: session lifetime, idle timeout, waiting_for_human semantics, return fields, error codes, local_cli_hint behavior, and multi-agent limitations. This is well above the baseline needed for an open-world, non-destructive mutation-like join operation.

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 critical purpose is front-loaded, but the description is a dense wall of clauses mixing return values, errors, workflow rules, and multi-agent distinctions. Much is useful, but the structure makes it harder to scan than it needs to be.

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 tool's complexity, annotations, output schema, and nine parameters, the description is complete enough to call it correctly. It covers lifecycle, returns, errors, timing, and operational constraints.

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 documents all parameters. The description nonetheless adds useful meaning for invite_url, label length rejection, greet timing, model visibility, and returned session fields, but it does not clarify every parameter such as quiet or data_channel 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 states a specific verb and resource: connect to a voicehook.ai voice call as the agent behind its voicebot. It clearly distinguishes this from create_call and other sibling tools by explaining the invite flow and session handle.

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 explicit usage conditions, including the hard rule after create_call, when to repeat join, and how several-agent scenarios should use the CLI instead of MCP/bridge. Alternatives and timing are named directly.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: the session handle becomes invalid afterwards, warning the agent not to reuse it. Missing only edge-case detail such as behavior on an already-invalid session.

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

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

Two tight sentences, zero filler, with the core action and the session-invalidation consequence both front-loaded. Every clause earns its place.

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

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

For a two-parameter mutation tool with an output schema and full annotation coverage, the description supplies the essential post-condition (invalid session). Only minor gaps remain, e.g. what happens if the session is already gone, which the idempotentHint partly signals.

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% (both `say` and `session` are documented, including the 4000-char limit and the join provenance). The description restates the optional `say` semantics but adds no syntax or format detail beyond the schema, so the 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+resource ('Leave the call') that any agent can distinguish from siblings like join, say, or status. The parenthetical clarifies the optional pre-leave utterance, which sharpens rather than muddies the purpose.

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?

Makes clear this is the tool for exiting a call and notes the optional pattern of speaking a goodbye first. It does not explicitly contrast with alternatives (e.g., why not just stop calling `next`), but the usage context is unambiguous and no exclusions are needed.

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?

Goes well past the annotations (readOnly, openWorld, non-idempotent, non-destructive), which only say this is a safe poll. It explains the 50 s cap, that timeout is a normal no-event result, that `reconnect: true` means a server restart, that `superseded` means a newer next call replaced this one, that `ended` carries budget/limit detail codes, and that 404 means the session is gone while 5xx/503/network errors leave it valid.

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 purpose and the hard join rule are correctly front-loaded, but the body is one enormous run-on sentence of nested parentheticals enumerating every event field. Much of that enumeration duplicates the output schema and forces the reader to parse a wall of text to find the two or three events that change behavior.

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 long-poll loop tool with this much branching behavior, nothing essential is missing: call sequencing, error recovery, stale/revise handling, decision routing, and the meaning of the less common events are all covered. With an output schema present, the field-level enumeration is arguably redundant but not a gap.

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

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

Schema coverage is 100%, so `session` and `timeout` are already documented, but the description adds the consequence of the timeout value — that elapsed time yields a `timeout` event with `reconnect: true` on server restart — which the schema does not express. The max-50 cap is repeated from the schema, adding no new information.

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 precise verb+resource+scope: 'Wait (up to `timeout` seconds, max 50) for the next event in the call and return it,' and the exhaustive event enumeration leaves no doubt what comes back. It never names `helper_next` as the alternative for helper sessions, so the sibling distinction is only implied by references to 'this one' vs 'another agent'.

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?

Strong operational guidance: 'keep calling next in a loop,' the hard rule to show share_text then join before any turn ends, the instruction to route helper_decision to that session and never answer it, and to answer question_check via decide. What's missing is an explicit exclusion pointing an agent at `helper_next`/`helper_status` when it is driving a helper rather than its own call.

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?

Goes well beyond the annotations (which only declare non-read-only, open-world, non-idempotent, non-destructive) by disclosing the whole escalation ladder: SMS with a 10-minute single-use link, auth requirement (logged in or PIN), 2-minute fallback to a phone call, account-level gating rules (opt-in, quiet hours, per-day, budget, credit), billing via billed_eur, and the refusal shape {status: refused, why}. That is exactly the operational context an agent needs before triggering a paid, side-effecting notification.

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

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

Front-loads the core action and escalation behavior, with the parameter notes compressed into the tail. Dense but nearly every clause carries new information; the return-shape enumeration is somewhat redundant given an output schema exists.

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 cross-channel, money-spending notification tool, the description covers trigger condition, delivery path, fallback timing, auth, gating rules, and failure modes. Since an output schema exists, the return-value enumeration is optional, and nothing an agent needs to invoke this 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 description coverage is 100%, so the schema already documents reason, message, and session. The description's 'reason: done | blocked | decision' and 'message: max 120 characters' merely restate the enum and schema text, adding no syntax or format meaning beyond it. Baseline 3 is correct when the schema carries the parameter semantics.

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 (notify the human owner via SMS) and immediately scopes it to the case where they are not on the call page. It is clearly distinguishable from sibling call_me and from status/decide/next, so an agent can pick it 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?

Explicitly says 'Prefer this over call_me' and gives the selecting condition ('when they are not on the call page'), which implies call_me is the alternative when the human is present. It stops short of stating the when-not case outright, so it is strong routing guidance rather than a complete decision 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 flag destructive, non-idempotent, and open-world behavior, and the description adds concrete consequences: overwrite discards not-yet-started says, revise changes the next event, live rooms paraphrase and return verbatim false, and ref highlights a card while speaking. It also discloses the return values ok and seq. This is consistent with destructiveHint=true rather than contradicting it.

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 purpose, then modes, ref, and return values, and every sentence carries useful information. The parenthetical 'verbatim false, mode live_paraphrase' is slightly dense, but it does not waste space.

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

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

With an output schema, rich annotations, and mostly documented parameters, the description is complete enough for correct invocation. It adds the key behavioral nuance around destructive overwrites and live-room paraphrasing that an agent otherwise would not know.

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 75%, and the description supplies the missing mode semantics in detail, including append, overwrite, and revise behavior. It also explains ref's highlighting effect and notes text is spoken verbatim in normal mode, adding meaning beyond the schema descriptions.

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: the voicebot speaks `text` aloud in the call. The title reinforces this, and the tool is clearly the speech primitive rather than a data, notification, or decision 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?

It gives explicit mode-selection guidance: append queues after earlier says, overwrite replaces this agent's not-yet-started says, and revise also causes the next tool to return a revise event. It does not explicitly compare the tool with siblings like notify_me or send_data, so it stops short of a 5.

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

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

Annotations only give the generic mutation/open-world profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description goes well beyond them: unknown recipients yield 404 with the call's labels, the 15000-byte inline cap yields 413, files over ~11 KB must go through POST /api/bridge/upload (up to 10 MB), base64 inflates size by 4/3, and receivers see a typed data packet served at a URL requiring Bearer session auth.

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 purpose and channel semantics are front-loaded, and nearly every clause carries operational information (limits, error codes, recipient format). It is a dense semicolon-chained paragraph, and the receiver-side packet format partially restates the output schema, so it is informative but not maximally tight.

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

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

For an 8-parameter tool with an output schema already present, the description still supplies everything an agent needs: size ceilings and the 413 failure mode, the upload fallback endpoint for large files, recipient resolution and the 404 behavior, and per-kind payload requirements. Nothing essential 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 88%, so baseline is 3. The description adds real meaning beyond the schema: it maps each kind value to the expected payload shape (json=any JSON, text=string, file=base64 plus name/mime or file_id), explains the '*' wildcard for to, and specifies that name/mime accompany file payloads. Only minor gaps remain, such as the optional id format.

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 (send JSON/text/file to other agents in this call) and immediately distinguishes itself from siblings by naming the channel's nature: 'silent data channel: never spoken, never shown to the human'. An agent can tell this apart from say/show 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 description clearly establishes the context of use (silent, non-spoken, non-visible to human, only one activity line shown), which implicitly routes the agent away from say/show for machine-to-machine payloads. It does not explicitly name those alternatives or state when-not to use this tool, so it stops short of a 5.

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

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

The description goes well past the annotations, which only say readOnlyHint=false, destructiveHint=false, openWorldHint=true. It discloses visible side effects (a preview appears top left, panels open or close), the hidden `context` channel the voicebot reads instead of the image, SVG sandbox restrictions (no scripts, no foreignObject, no external references), and per-kind size limits — all behavior an agent could not infer from structured fields.

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 purpose is front-loaded correctly, but the rest is a single dense run-on paragraph mixing content kinds, panel semantics, SVG rules, file kinds and limits, which makes it hard to scan. Some sentences duplicate what the schema already documents (the 4000/80/300 KB/1024 KB/10 MB/2 MB limits appear in both places), so not every sentence earns its place.

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

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

For a 12-parameter tool with seven rendering kinds, the description covers the decisions an agent must make: which kind, when `context` is mandatory, when `file_id` replaces inline data, and what the page does afterward. An output schema exists so return values need no explanation, but the description is silent on failure behavior when a limit is exceeded and on the relationship to `helper_show`.

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 schema coverage at 83% the baseline is already 3, and the description pushes higher by explaining cross-parameter constraints the schema states only in isolation: image kind REQUIRES `context`, `large` implies panel cards, `link` takes exactly one URL, and `file_id` exists specifically to keep large base64 out of the tool call. It loses a point for repeating size limits already in the schema and for saying nothing about the `goal` parameter's inheritance behavior.

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 gives a concrete verb and resource — "Put a card on the person's call page" — and immediately bounds the scope with "(never spoken)", which cleanly separates it from the sibling `say`. It then enumerates the exact content kinds it renders (text, code, link, image, plus pdf/csv/md later), so an agent can tell what it is for without consulting 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?

Guidance is rich at the level of kinds: code is monospace with a copy button, link takes exactly one http(s) URL, image requires `context`, `large: true` is for diagrams and swimlanes, `panel` opens/`none` closes specific views. What it never does is name the alternatives explicitly (e.g. `say` for spoken output, `helper_show`, `send_data`), so the routing decision is implied by "never spoken" rather than stated as a when-to-use 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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses replacement semantics, hidden-vs-visible meta content, the warnings-not-error degradation when context/faq are missing, and the emoji keep/remove behavior. It stops short of saying what the prior board's contents are lost or how partial updates behave, but the destructive overwrite is clearly implied.

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

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

Front-loaded with the core action and the sibling routing, then limits and meta semantics. It is dense and somewhat run-on with per-field char caps inline, but nearly every clause carries operational information rather than restating the name.

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

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

For an 8-parameter mutation tool with an output schema and annotations, the description covers board structure, hidden meta, warnings behavior, and the return fields (ok, humans_present, warnings). The `goal` inheritance parameter is only handled by the schema, which is a minor gap given the otherwise thorough coverage.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: meta entries are hidden background never shown on the page, missing context/faq yields warnings rather than failure, and emoji empty-string removes while omission keeps. It does not touch `goal` or `session`, leaving those entirely to the schema.

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

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

The description opens with a specific verb and resource ('Replace the agent's status board on the call page with this one') and immediately clarifies the artifact is never spoken but read by the voicebot. It also distinguishes itself from the sibling decision board by routing person-directed questions to 'decide'.

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 explicitly names the boundary: this board is for progress only, and questions for the person belong on the Decision Board (decide). That is a concrete when-to-use/when-not-to-use rule tied to a named sibling, so an agent can route correctly 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?

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true); the description adds real context beyond them by scoping which card operations are reachable here and by stating the return shape. It does not explain the semantics of the individual operations — notably whether 'pick' claims the card exclusively or what 'release' restores — which matters for a non-idempotent mutation.

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

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

Three tight sentences, front-loaded with the core action and the operation list before the restriction boundary. The trailing 'Returns {ok, card}' is slight duplication given an output schema exists, but it costs almost nothing.

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?

The output schema makes the return explanation unnecessary, and the CLI-only restriction is well covered, but the description never explains what 'pick', 'done' or 'release' actually do to the board state. For a five-parameter, non-idempotent mutation tool, an agent still has to infer the core semantics of the operations from their names alone.

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 every parameter including 'nr', 'session' and the op enum is already documented in the schema. The description mirrors that mapping (update→note, done→proof) without adding syntax, constraints, or meaning for the opaque op values 'pick' and 'release'. Baseline 3 is appropriate when the schema carries the load.

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+resource ('Changes one card of the account task board') and enumerates the four allowed operations (pick, update, done, release), which lets an agent distinguish it from the sibling 'tasks' listing tool. It stops short of naming that sibling explicitly, so the differentiation is implied rather than stated.

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

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

Provides an explicit when-not boundary: moving, renaming, assigning and discarding cards must go through the owner's voicehook-agent CLI with an agent key, not this tool. What is missing is a positive pointer to the read-side alternative (e.g. 'tasks' for listing/inspecting cards), so the routing guidance is one-sided.

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, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts beyond that: the ownership/agent-key precondition and the concrete 403 not_owner_agent failure mode, which an agent cannot derive from annotations or schema.

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

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

The definition is front-loaded with purpose, then the return shape, then scope, then the failure condition, with no filler sentences. Every clause, including the return-shape sketch, 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 an output schema present the description need not fully explain return values, yet it still previews the card fields, and it covers the access precondition and enum scopes. The remaining gap is the lack of differentiation from the sibling `task` tool for a board-based read operation.

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 parameters are already documented, establishing a baseline of 3. The description adds real meaning for one enum value ('mine (assigned to or picked by this agent)'), but leaves the distinction between 'mine' and 'assigned' and the meaning of 'open' unexplained.

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 ('Lists cards of the account task board (Kanban)') and narrows the audience (the call owner's board, viewed by an agent the owner brought in). It never names the sibling `task` tool explicitly, so the agent must infer the boundary between listing cards and the singular task tool, which keeps this from a 5.

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

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

Usage context is implied through the scope enumeration and the access precondition ('Agents of guests get 403 not_owner_agent'), which tells the agent when the call will fail. However, there is no explicit statement of when to choose this over `task`, `activity`, or `decisions`, and no when-not guidance beyond the 403 case.

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 the write/mutation profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false), so the safety bar is lower. The description adds that effects are immediate and equivalent to the user's own clicks, which is useful context, but says nothing about reversibility, failures, or whether 'close' loses state.

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 and free of filler, but rendered as a single run-on sentence with deeply nested parentheses that makes the subcommand grammar hard to scan. Compact in length, weak in structure.

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 7-parameter tool with an output schema (so return values need not be explained), the description covers all four commands, their parameter combinations, and the usage gate. Only minor omissions remain, such as the undocumented 'ring' window value and undefined behavior for incomplete command/parameter combinations.

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 only 14% (session alone), so the description must carry the load, and it largely does: it maps each cmd to its companion parameters (win+state for window, preset for layout, win+slot for move, project for focus), which is the co-occurrence logic the schema cannot express. It does omit the 'ring' win value present in the enum, a small gap.

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

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

States a specific verb and resource: change the person's call page layout immediately, with an explicit subcommand breakdown (window/layout/move/focus) that maps onto the cmd enum. An agent can tell it mutates the live UI. However, it never distinguishes itself from siblings like 'show', 'activity', or 'status', which also touch what the user sees, leaving overlap unresolved.

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

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

Provides an explicit gating condition ('only when the person asks for it or it clearly helps') plus a concrete example (open decisions after asking one), and rules out narration ('never spoken'). It stops short of naming any alternative tool or stating when NOT to use it versus siblings.

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