voicehook

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the mutation/append profile is partly covered. The description adds real behavioral context beyond that: the entry is one line of 3-8 words, it appears as a timestamped line on the call page, and it produces no speech output. It does not say whether entries can be edited or removed.

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, the action and its target front-loaded, with the key constraint and the 'Never spoken' caveat placed where they are read immediately. No 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. For a simple two-parameter append tool, the description plus structured fields are nearly complete; only edit/removal semantics and any rate or length-error behavior are unaddressed.

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

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

Schema description coverage is 100% and both parameters (text, session) are documented in the schema, so the baseline is 3. The description reinforces the 3-8 word limit on text but adds no format, encoding, or session-handling detail beyond what the schema already states.

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+effect: 'Append one line ... to the activity feed on the call page, shown as a timestamped line.' The trailing 'Never spoken' implicitly separates it from the sibling 'say' tool, but it never names that sibling, so the differentiation is inferential 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?

'Never spoken' gives an implied contrast with the audio-producing 'say' tool, which helps an agent choose between them. However, there is no explicit when-to-use statement, no prerequisite mentioned (beyond the schema's note that session comes from join), and no exclusions.

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 only flag non-readonly, open-world, non-idempotent), it discloses concrete behavior: the free-allowance/credit cost model, the browser requirement that an in-app browser blocks the microphone, link expiry via expires_in, and a 429 rate-limit error. This is exactly the kind of operational context annotations cannot carry.

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 is front-loaded in the first sentence, followed by a compact enumeration of return fields and the error case. It is dense but each clause carries operational meaning; only the return-field list is somewhat heavy given an output schema already 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 zero-required-param creation tool with an output schema, the description still supplies everything an agent needs: purpose, the meaning of each returned link, expiry semantics, the browser caveat, and the rate-limit error. Nothing material 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 67%. The description restates lang (de/en, default de) which the schema already documents, and says nothing about `name` or `mode`. With the schema doing most of the work and `mode` undocumented in both places, this sits at 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?

The description opens with a specific verb+resource ('Start a new voicehook.ai voice call') and the title reinforces it. It is clearly distinguishable from siblings like join, leave, say, and status, which operate on an existing call.

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 conveys the call-creation flow implicitly: it produces human_url (the human opens it to start) and operator_invite_url (the agent's link for join), which tells the agent this precedes join. However, it never states explicit when-not-to-use conditions or named alternatives for edge cases.

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 by disclosing the 422-on-overflow rule with no truncation, the async return (id and number) and the exact shape of the later `next` event including verdict enums. The mutation workflow (change with id plus new fields, remove with delete true) is spelled out, consistent with destructiveHint=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?

Front-loaded with the purpose, then constraints, then the async answer contract in a tight block. Dense and information-rich, though the run-on constraint list could be split for readability.

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 limits, the update/delete path, and the asynchronous answer contract. Given an output schema exists, the description rightly avoids restating return structure but still explains the `next` event, which the output schema alone might not make clear.

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 options, recommend, delete, and id. The description mostly restates those constraints (2-3 options, 40 chars, 160 chars) and adds the 422 consequence, which is behavioral rather than parameter meaning. 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 and resource: putting a question on the call's Decision Board, with the rendered form (shown as #number with buttons). This is clearly distinguishable from siblings like say, show, or send_data, which push content rather than solicit a decision.

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 covers the create/change/delete modes and notes the person can answer by voice, which implies usage, but never says when to prefer decide over say or show. An agent must infer that this is the tool for soliciting a choice rather than merely broadcasting one.

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 generic profile (not read-only, open-world, non-idempotent). The description goes well beyond them: session lifetime ('valid until the call ends, after 10 min without next or say, or after leave'), the non-error waiting_for_human state, and a full error taxonomy (403/409/410/429/503) with the note that a 503 restart leaves the call 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?

Front-loaded with purpose, then params, returns, and errors in a logical order; every clause carries information. It is a single dense paragraph that could be broken into labeled sections, 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?

Although an output schema exists, the description still enumerates the returned fields (session, room, lang, idle_timeout_s, peers, humans_present, context) and covers failure modes and the idle-timeout semantics, so an agent has everything needed to call and interpret it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description still adds value: invite_url must include '?invite=', label is rejected if over 22 chars, greet fires 'right after the join (or when the person is back, if they are out)', and model is internal-only — details that sharpen the schema's own text.

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 — 'Connect to a voicehook.ai voice call as the agent behind its voicebot' — which cleanly separates it from the sibling create_call (which makes the call rather than joining one). An agent can identify the operation 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 explains where the invite_url comes from ('from the person or from create_call') and what happens with a create_call link (waits up to 50 s, returns waiting_for_human), which gives clear usage context. It stops short of an explicit when-to-use-vs-sibling rule, 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds a genuinely non-obvious behavioral consequence beyond the annotations: the session handle becomes invalid after the call, which tells the agent this operation cannot be retried with the same handle.

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, with the action and its optional modifier front-loaded and the side effect placed second. 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?

An output schema exists, so return values need no explanation, and the one critical side effect (invalidated session) is disclosed. Coverage is strong for a small tool, with only minor omissions such as error behavior when the session is already gone.

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 'session' and 'say' are already documented in the schema (including the 4000-char limit). The description's mention of an optional goodbye adds a usage example but no semantics 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 and resource ('Leave the call') and clarifies the optional narration behavior, so an agent can distinguish it from siblings like join, say, and next. It does not explicitly name an alternative tool the way a 5 would, but the purpose is unambiguous.

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

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

Usage is implied rather than stated: the parenthetical about optionally speaking 'say' first signals it is the terminal action in a call lifecycle, and 'session handle is invalid afterwards' hints at when it cannot be reused. There is no explicit when-to-use/when-not guidance or named 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 cover only the safety profile (readOnly, not destructive, non-idempotent, open world), leaving the heavy lifting to the description, which delivers: timeout semantics, the full event taxonomy, `humans_present`/`addressed_to` fields, `stale_error` conditions, and explicit error handling (404 = unknown session after leave; 5xx/503/network errors leave the session valid). This is unusually rich behavioral disclosure well beyond 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 core instruction is front-loaded in the first clause, but the rest is a single mega-sentence with a deeply nested parenthetical cataloguing every event type. Since an output schema exists, much of that event enumeration is redundant with structured return data, and the run-on nesting makes it hard to parse.

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 long-poll tool this is nearly complete: session provenance, timeout bounds, event semantics, and error/session-validity rules are all present, and the output schema covers return shapes. The remaining gap is operational follow-up guidance (what to do after `ended`/`timeout`, concurrency limits), which leaves it just short of full completeness.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, including the default (45) and maximum (50). The description repeats the timeout cap and the session origin but adds no syntax or format meaning 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?

The opening sentence gives a precise verb+resource+scope: block up to `timeout` seconds for the next event in the call and return it. It clearly distinguishes the operation from mutation tools like say/send_data. It does not, however, name or contrast itself with close siblings such as `activity` or `status`, which is what a 5 would require.

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 implicit: the event semantics (e.g. `timeout` with reconnect, `superseded` when a newer next call replaces this one) imply a polling loop and discourage concurrent calls, but the description never states when to call this versus `activity`/`status`, nor what to do after `ended` or an error. Guidance is inferable but not 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?

Annotations already declare destructiveHint=true and idempotent=false, and the description usefully adds that `overwrite` replaces this agent's not-yet-started says (the destructive surface) and that `append` queues behind earlier says. It also discloses the live-room paraphrase behavior and the `verbatim: false` outcome, which annotations cannot express.

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 dense paragraph, front-loaded with the core action before the mode semantics. Every clause carries information, though the parenthetical live-room aside is slightly heavy for a single sentence.

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

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

With an output schema present, return values need not be described (though it mentions ok/seq) and annotations carry the safety profile. The description still supplies the mode-queue semantics and live-room nuance an agent needs, leaving only permission/prerequisite details 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 67%: `text` and `session` are documented in the schema, but the `mode` enum values are not. The description compensates by defining each enum value's exact effect, which is real added meaning beyond the structured data.

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 ('The voicebot speaks `text` aloud in the call') and immediately clarifies its scope (verbatim in normal mode, rephrased in a live room). It is clearly distinguishable from siblings like `show`, `decide`, and `next`, though it never explicitly names those alternatives.

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

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

The description thoroughly explains the *mode* parameter values (append/overwrite/revise), which is effective parameter-level guidance. However, it gives no explicit guidance on when to use `say` versus sibling tools such as `show`, `send_data`, or `decide`, so tool-selection context is only implied.

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 cover the generic write/open-world profile, and the description adds substantial behavior: 404 on unknown recipient, a 15000-byte inline cap with 413, base64 inflating files by 4/3, an 11 KB–10 MB upload path, and the exact receiver-side shape. This is exactly the extra context annotations cannot provide.

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

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

Front-loaded with purpose and the channel rule, and every clause carries operational information (limits, errors, receiver format). The single dense run-on paragraph is harder to scan than a structured list, 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 an 8-parameter tool with file handling, the description covers delivery semantics, error behavior, size limits, auth for retrieved URLs, and receiver format, even though an output schema exists and return values need not be explained. Nothing needed 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 88%, so the baseline is 3, but the description adds real meaning beyond the schema: 'to' accepts label/identity/'*' with a 404 fallback, 'payload' semantics are mapped per kind, and the upload-endpoint/size rules for 'file_id' are stated. It largely mirrors the schema for the simpler params, so it lands above baseline rather than at the top.

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 or a file to other agents in this call') and immediately scopes it as a silent data channel, which cleanly separates it from siblings like say and show. An agent can distinguish it without opening any schema.

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

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

The parenthetical that the channel is 'never spoken, never shown to the human, never to the voicebot' strongly implies when to prefer it over say/show, and the human-visibility rule is spelled out. It stops short of naming the sibling tools explicitly as alternatives, so it is clear context rather than a full when/when-not routing 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 declare this is a mutating (readOnlyHint=false), non-idempotent, non-destructive, open-world call. The description adds real behavioral detail beyond that: cards render as a small preview top-left, panel values change UI state (cards/board/log/decisions open, none closes), and hard size limits are given. It still doesn't say whether cards accumulate or replace previous ones, which is the main remaining ambiguity.

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 is front-loaded in the first clause, kind semantics follow, then UI behavior, then limits — a sensible order with almost no filler. It is dense, packing four distinct topics into a short block, which costs a little readability but wastes no sentences.

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

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

With annotations covering the safety profile and an output schema handling return values, the description carries only what is needed: purpose, kind semantics, panel effects and size limits. The only gap is usage routing versus siblings and whether successive cards stack or replace, which is minor for this tool.

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

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

Schema coverage is 67%, and the two undocumented parameters (`kind`, `panel`) are exactly the ones the description explains in depth: per-kind semantics (code shows a copy button, link must be exactly one http(s) URL, image accepts SVG text or base64 PNG/JPEG/WebP) and per-panel effects. It also restates limits for text, title, SVG and raster sizes. That compensates well for the schema gaps.

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 ("Put a card on the person's call page") and immediately qualifies it with "(never spoken)", which cleanly separates it from the spoken-output sibling `say`. It then enumerates the four card types, so an agent knows exactly what this tool produces 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 "never spoken" qualifier implicitly routes the agent away from `say`, and the panel sentence explains what happens when each panel value is used, including `none` closing them. It gives clear context for use but never names the alternative tool or states an explicit when-not condition.

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 destructiveHint=true and idempotentHint=true; the description corroborates this by describing replacement of the existing board and adds per-field limits (400/200/2000 chars, 10 items, 6 pairs) plus emoji removal semantics. It does not clarify what happens to open/done/faq when they are omitted (null default), which is the key behavioral question for a destructive replace.

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, then structured as compact per-field constraints with no filler sentences. Every clause carries information an agent needs to fill the payload correctly.

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

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

An output schema exists, so the brief 'Returns ok and humans_present' is a harmless redundancy rather than a necessity. The description covers constraints and emoji behaviour well; the remaining gap is whether omitted open/done/faq clear or preserve existing board content on a destructive replace.

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 the whole-board 2000-character budget and the 'empty string removes it, left out keeps it' rule for emoji, neither of which is fully stated in the schema. The omitted-field behaviour for the other parameters remains unaddressed.

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 ('Replace the agent's status board on the call page with this one') and immediately scopes it against the sibling verbs by noting it is 'never spoken', unlike say. An agent can distinguish this from say/show/send_data without opening any schema.

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

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

Explains the operating context clearly: this writes the board that the voicebot answers the person's progress questions from, which implies when it should be used instead of speaking. It does not explicitly name alternatives or state when not to use it, 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.