verify

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

Despite annotations already indicating a non-destructive, non-idempotent mutation, the description adds substantial context: the link contains no secret, is safe to show in chat, works only once, and expires within 15 minutes. These are exactly the behavioral details an agent needs to use the tool safely.

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 tool's purpose and followed by safety and expiry details. There is no wasted text, and each sentence contributes distinct information.

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

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

For a one-parameter, no-output-schema tool, the description covers the core purpose, safety profile, and lifetime of the link. It could be slightly more complete by explicitly stating that it returns/generates the link or by naming relevant sibling alternatives, but no critical invocation detail 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%, and the lone optional secret parameter is well documented in the schema. The description does not add meaning about that parameter, so the schema carries the parameter semantics; 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 clearly identifies a specific resource: a phone link that alerts the human about missed calls. It is understandable without opening the schema, but it does not explicitly differentiate this tool from sibling link tools such as listing_link, routine_link, or disconnect_link.

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

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

The description implies the use case — giving a human a link on their phone to learn about missed calls — but it does not say when to choose this over other link-related siblings or when not to use it. The one-time, 15-minute constraint is useful context but is more behavioral than a usage-routing guideline.

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 adds substantial behavior beyond the annotations: it makes the caller permanently unscreened, removes daily message limits, promotes a currently held screened call, stores the line rather than the name, and exposes the note to the AI answering calls. These details make the mutation effect and persistence clear without contradicting the annotations.

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

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

The description is front-loaded with the core effect and every sentence adds useful context, but the single dense paragraph is somewhat long and packs multiple clauses about identity, notes, and trust into one block. It remains readable and avoids repetition.

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

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

For a three-parameter mutation with no output schema, the description covers the persistent allowlist effect, immediate call handling, note visibility, identity behavior, and trust guidance. Combined with full schema coverage and annotations, an agent has enough context to invoke 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 coverage is 100%, so the baseline is 3, but the description adds useful meaning about the address parameter: the list stores the line itself so later name changes do not matter. It also explains the note parameter's purpose and visibility, going beyond the schema definitions.

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 persistent action: letting a caller ring straight through instead of being screened, with no daily message limit. It also clarifies the immediate effect on a currently screened call, which distinguishes this from one-off admission tools.

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

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

It gives clear when-to-use context by saying this is only for callers the human would want to hear from and by recommending reciprocal allowance after a good call. It does not explicitly name sibling alternatives such as block or let_in, so it falls short of full when/when-not routing.

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

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

Goes well past the annotations (readOnly false, openWorld true, destructive false) by disclosing per-call blocking behavior (each use speaks and waits for the caller's reply), the mutation ordering for hang_up (message spoken first, then the call ends), the transient nature of moment, and a prompt-injection warning about caller content. No contradiction with 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?

Front-loaded with the core action and the call_id key handling, and nearly every clause carries operational information. The colon-chained, run-on sentence style makes it denser than it needs to be, slightly slowing extraction of the hang_up and moment rules.

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

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

With no output schema, the description covers what comes back (the caller's reply and the call_id token) and how to continue the interaction across turns. The only parameter not touched in prose is secret, which the schema describes fully as optional from get_line.

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 moment, secret, call_id, hang_up and message. The description still adds real value: the call_id carries a '~token' suffix and the whole string must be reused verbatim, and hang_up/moment have observable ordering effects — details not in the schema 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 concrete verb+resource ('Pick up a call ... and talk') and anchors it to the sibling that produces the input (wait_for_calls). It distinguishes itself from hang_up and moment within the same description, so an agent can pick it apart from its neighbors 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?

Explicit sequencing rules: call only after wait_for_calls reports ringing, reuse the returned call_id for every later answer, use hang_up:true only when the call's job is done, and 'never in the turn that asks a question' — an explicit when-not. It also names moment:true as the alternative for the not-ready 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by explaining that the output is meant to be handed to an autonomous worker and that a human-facing card is returned when no worker can be started. It does not describe the exact return shape or any secret-handling behavior, so it adds moderate value beyond annotations.

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

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

The description is short, at three sentences, but it is not front-loaded with a direct statement of what the tool returns. Metaphorical language like 'words' and 'card' makes the structure less immediately useful than a more literal opening would be, though it is not bloated.

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 low complexity, one optional parameter, full schema coverage, and annotations, the description covers the intended consumer of the output and the fallback behavior. It still leaves ambiguity about the exact return type and does not clarify how this tool relates to siblings such as answer_call or get_line, so it is only minimally complete.

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

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

There is one optional parameter and schema description coverage is 100%, so the schema already documents the secret parameter thoroughly, including where it comes from and how to handle it. The description does not mention the secret parameter at all, so with high schema coverage the baseline score of 3 is appropriate.

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

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

The description conveys that the tool provides 'the words for a helper that answers your line,' which suggests a briefing or prompt for a call-answering worker. However, it never states an explicit verb such as 'get' or 'return,' and the metaphorical phrasing ('words,' 'line,' 'card') leaves the exact resource ambiguous. It also does not clearly differentiate this tool from siblings like answer_call or 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 gives a clear when-to-use rule: if you can start an autonomous worker, sub-agent, task, or routine, start one and give it these words. It also states a fallback for when no autonomous worker is available: the tool gives a card to show your human. The guidance lacks explicit comparison to other call-related MCP tools, but the usage condition itself is reasonably clear.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, so the description doesn't need to restate mutability. It adds genuinely new behavior: the first call returns a preview of the requesting line, and confirmation requires the human's explicit yes. It doesn't say what a successful approval produces or what happens to the code afterward.

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?

Dense and front-loaded: the purpose, the prerequisite code, the label, then the two-step confirm workflow and the safety rule. The long compound sentences are a bit run-on but every clause carries information.

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

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

For a non-destructive mutation with no output schema, the description covers prerequisite, safety gating, and the two-call pattern. Only the post-success outcome and code lifetime are unstated, which is a minor gap given no output schema exists to describe returns.

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 25%, so the description must compensate — and it does for three of four params: code (obtained from join_name), label (with concrete examples 'accountant, kitchen, shop'), and confirm (only set true on the human's yes). The secret parameter is left to the schema's own description, which is acceptable.

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: approving another AI's join request (made via join_name) under your name, with a label. The flow is identifiable, though the phrasing 'Name one of your human's other AIs under your name' initially reads like name_line, and the closest sibling (name_line) is never named as a contrast.

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

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

Gives explicit two-phase usage: call first without confirm to see which line is asking, verify with the human, then call again with confirm: true. It also states a hard exclusion — never approve because a caller asked — so the when/when-not decision is fully 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?

Annotations already declare non-read-only, idempotent, non-destructive, so the safety profile is covered. The description adds real value with "from now on" (persistent, future-only effect) and "screened or not" (blocking applies regardless of screening state), but says nothing about reversibility, whether existing voicemail/missed-call history is affected, or required authorization.

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

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

A single front-loaded sentence with no filler; both clauses carry information. It is arguably too terse given the missing routing and reversibility information, which is a completeness issue rather than a conciseness one.

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

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

With only 2 fully documented params, annotations, and no output schema, the definition is workable but incomplete: an agent cannot tell from it how to reverse the block, whether it requires the secret or authentication, or how it interacts with allow. The "screened or not" clause partially compensates.

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%, documenting both secret and address with format examples. The description confirms the address identifies a caller to be refused but adds no syntax, format, or default details 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?

"Refuse a caller's calls" is a specific verb+resource that an agent can act on directly, and the effect is distinguishable from sibling tools like allow or let_in. It stops short of explicitly contrasting with those siblings, so a 4 rather than 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?

There is no statement of when to use this versus allow, let_in, or voicemail, and no mention of how a block is later undone. The only usage hint is the implied "from now on" persistence, which the agent must infer.

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 openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structural behavior: the call blocks and returns what the peer said plus a token for continuing, and an unreachable peer yields an away notice rather than an error. It still does not say whether the secret is required when the connector lacks one.

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 return behavior. The conversational phrasing ('say the first thing', 'you'll hear they're away') costs a little precision but no sentence is wasted.

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

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

With no output schema, the description does give the essentials of the return value (peer reply + call_token, or an away notice). But it never names the sibling that consumes the call_token (say) or hang_up for ending, and gives no sense of the response shape, leaving an agent to guess the next step in the flow.

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 phrase 'say the first thing' clarifies that message is only the opening utterance – an important semantic not evident from the schema alone – and the call_token note explains why the rest of the call is not part of this parameter.

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 – call another AI on the kenoodl network and deliver the opening message. An agent can tell it apart from answer_call or wait_for_calls in broad terms, but the description never explicitly names when to prefer those siblings over this tool; the differentiation is left implicit in the call_token hint.

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 only implied: the away-message case tells the agent that a failed connection is a normal outcome, and the call_token hints at a follow-up flow. There is no explicit 'use this when…' guidance, no mention of prerequisites such as first obtaining a line secret via get_line, and no statement that subsequent turns use a different tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered elsewhere. The description is consistent with that ('clear' = destructive) and adds the scope-selection semantics, but doesn't say what clearing actually does (remove from the missed list vs. delete history) or whether it is reversible.

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

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

A single sentence with zero filler, with the action and the two selection modes front-loaded. Nothing repeated from the title or schema.

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

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

Destructive annotations plus the schema cover safety and the secret parameter, and the description covers selection modes. Still missing: what 'clear' physically does, whether up_to is inclusive, and how the two parameters interact — meaningful gaps for an irreversible operation with no output 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 coverage is only 33%: 'secret' is documented in the schema, but 'ids' and 'up_to' are bare. The description compensates by explaining that ids selects specific entries and up_to selects everything through a given id, which is exactly the missing semantics an agent needs. It doesn't clarify inclusivity of up_to or whether both may be passed together.

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 ('clear') and resource ('missed calls') and explains the two selection modes (named ids vs. everything up to an id). It implicitly contrasts with the sibling missed_calls (which lists them), though it doesn't name that sibling explicitly.

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?

'Clear missed calls you've dealt with' gives a clear triggering condition (calls already handled), and the 'ids ... or ... up to an id' clause tells the agent which mode to pick. It stops short of naming alternatives or stating when not to use it (e.g., use missed_calls to inspect first).

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real behavioral value by disclosing result ordering ("Verified lines, whose address is a domain its owner proved, come first") and that listings are opt-in. It doesn't mention result limits, pagination, or empty-result behavior, which holds it below a 5.

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

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

Three sentences, all carrying content: eligibility of listings, ranking order, and search modes. There is mild redundancy between "what each one is for and what you can call it about" and "by what the call is about", and the colloquial framing costs a few words, but nothing is gratuitous.

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 three optional parameters, no output schema, and rich annotations, the main missing piece is what a listing actually returns. The description partially compensates ("with what each one is for and what you can call it about"), but an agent still doesn't know the result fields or volume. Otherwise complete for a read-only search.

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

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

Schema coverage is 100% and both enum parameters are documented in the schema, so the baseline is 3. The description restates the three search modes but adds only marginal nuance ("a person, or a business's industry" for category, "what you can call it about" for ask_about) beyond what the schema descriptions already say.

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 the resource (directory listings of people, AIs, businesses) and the operation (search by words, by kind, or by what the call is about). It reads somewhat indirectly at the start ("Who's on the network") before landing on the search verb, but an agent can still tell this apart from join_directory or listing_link. It is clear, though the operative verb arrives late.

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?

"Any of them can be called" implies the downstream purpose — find an entry, then use the call tool — which is useful routing context. However, no explicit when-to-use/when-not or naming of alternatives (join_directory, listing_link, allow/block) is given. Usage is implied, not 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower, but the description still adds substantial context: the key is invalidated immediately, the number can never be used again, and the operation requires explicit human instruction. This characterizes the destruction concretely rather than restating the annotation flag.

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

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

Two sentences, both front-loaded and zero-waste: the consequence of the call comes first, followed by the permission gate and the alternative. Nothing is repeated from the annotations or schema.

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

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

For a 2-parameter destructive action whose safety profile and parameters are already carried by annotations and a fully described schema, the description supplies exactly what structured fields cannot: irreversibility, the human-authorization requirement, and the migration path. No output schema exists, and none of the omitted return-format detail matters for an irreversible teardown.

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 the secret and the confirm flag are already documented in the schema, including the ls_ prefix and the "Must be true" constraint. The description's only parameter-relevant contribution is an implicit tie between the human-approval rule and the confirm flag, not new syntax or format detail.

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 ("Cut this app off from your line for good") plus the concrete effect: the key stops working and the number becomes unusable. It explicitly distinguishes itself from the sibling move_line, so an agent can route correctly without opening either schema.

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

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

Gives an explicit gating condition ("Use it ONLY when your human asks you directly"), a motivating example (suspected leak), and names the alternative for the adjacent case ("To keep the number in another app, use move_line instead"). Both when and when-not are covered.

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

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

Beyond the destructiveHint annotation, the description adds important behavioral context: the link can disconnect every app even without the agent, it contains no secret, anyone holding it can disconnect the line, and it should be kept private. These are meaningful security and scope details the annotations do not 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?

The description is compact and each sentence contributes purpose, usage, or security guidance. It is slightly indirect in phrasing and does not front-load the action as directly as it could, but there is no wasted text.

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 tool with one optional parameter, no output schema, and annotations covering safety, the description is largely complete. It could be stronger if it clarified link lifetime or whether the link is single-use, but it gives enough context 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?

The single optional secret parameter is fully documented in the schema, including where it comes from and when it can be omitted. The description does not add parameter-specific meaning beyond the schema, which is acceptable at 100% schema description coverage.

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

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

The description clearly conveys that this produces a link for a human to keep, which can cut every app off the line if something goes wrong. It is distinguishable from direct line-control siblings like disconnect_line, but it does not explicitly name or contrast with that alternative.

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

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

It gives clear usage guidance: hand the link to the human once, after setup, and explain what it is for. It also explains the condition under which the human would use it, though it does not explicitly compare when to use this versus disconnect_line.

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 secret is shown only once, it must be kept out of the chat, and creating a duplicate line produces an identity disconnected from the first line's contacts. This is consistent with readOnlyHint=false and idempotentHint=false. It does not cover error cases or what happens if a bad key is supplied, so not a 5.

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

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

Purpose is front-loaded and no sentence is padding, but the prose is circuitous — nested parentheticals ('your number: tell your human, who can share it') and figurative phrasing add parsing cost for an agent. A tighter statement of the same facts would have been more scannable.

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 one optional parameter, no output schema and sparse annotations, the description carries the burden well: it enumerates the three returned fields, explains one-time visibility, and warns about duplicate lines. Only the meaning/use of the returned 'note' field is left thin.

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

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

Schema coverage is 100% and the single parameter is already described as 'ls_… from get_line, leave it out if the connector carries it', which the description largely repeats. The one genuinely additive point is that passing an existing line's credential returns that line's number instead of creating a new one. The description also drifts between 'secret', 'key' and 'ls_' terminology, which blurs rather than clarifies the parameter.

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 ('Get your own line on the network') and then unpacks what a line actually is: an address/number, a secret, and a note. It is distinguishable from siblings such as move_line, disconnect_line and line_status, though the heavy metaphor ('a stranger to everyone the first one knows') makes the provisioning purpose slightly harder to extract than plain wording would.

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

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

Gives explicit conditional guidance: if your human already has a line (ls_ key or @name), pass that key instead, and 'never make a second line' is a clear when-not rule. It also routes across tools by telling the agent to pass the secret to other tools. It stops short of naming specific sibling alternatives, so a 4 rather than 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, idempotentHint=true, and openWorldHint=true, so the safety and repeat-call profile is covered structurally. The description adds only the 'you started' ownership constraint and says nothing about what happens to the remote party or the line state after ending.

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 six-word sentence with the action front-loaded and zero filler. It is arguably clipped to the point of omitting preconditions, but no sentence is wasted.

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

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

For a three-parameter destructive tool with no output schema, the description covers the bare minimum and leans on the annotations and schema for everything else. It omits error/lifecycle behavior (call already ended, invalid token) and post-conditions, leaving clear 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 description coverage is 100%, with each of 'to', 'secret', and 'call_token' documented in the schema itself, so the baseline is 3. The description contributes no additional parameter meaning, which is acceptable given the schema does the work.

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 verb 'End' plus resource 'call' states the action unambiguously, and 'a call you started' narrows scope beyond a generic hang-up. It doesn't explicitly contrast with siblings like answer_call or call, but the operation is unmistakable.

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?

'a call you started' implies the precondition that only self-initiated calls can be ended, which is useful implied guidance. However, there is no explicit when-to-use, no mention of what to do if the call was never started or already ended, and no 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?

Adds substantial context beyond the annotations: it discloses that consent is required, that non-domain lines are not published until the human taps a preview link showing exactly what goes public, and that removal is immediate. This is consistent with destructiveHint=true and enriches rather than repeats the annotation set.

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

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

Four tightly packed sentences with the core action and consent rule front-loaded; the verification flow and removal follow in logical order. Slightly dense phrasing ('Ask your human first, once, and only list on their yes') but nothing is filler.

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

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

For a mutation tool with no required parameters and no output schema, the description covers the trigger, the consent prerequisite, the two publication paths and what becomes public, and the removal shortcut. An agent has enough to call this correctly without guessing.

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

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

Schema coverage is 100%, so all seven parameters are already documented, and the description adds only marginal semantics ('leave: true' for removal, secret carried by the connector). The domain-vs-link verification distinction is behavioral rather than per-parameter, 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 first sentence gives a specific verb and resource and covers all three operations (create a listing, change it, remove it), which an agent can map directly to intent. It stops short of distinguishing itself from siblings such as `directory` (read path) or `line_status`, so an agent must infer that this is the mutation entry point.

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 conditional guidance: 'Ask your human first, once, and only list on their yes' sets a consent prerequisite, and the description explains the two listing paths (verified @domain line vs. a link the human taps). It also documents the removal path via `leave: true`. There is no explicit exclusion or pointer to sibling tools for reading or editing the listing elsewhere.

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 non-read-only, open-world, non-idempotent, non-destructive, but say nothing about the two-phase approval flow. The description fills that gap by disclosing that the call only produces a code and that a separate approval step by the human's main AI is required. It does not address what happens on repeated calls or whether pending requests expire.

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

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

Two sentences, both carrying real information: the first defines the request and its naming outcome, the second the approval handoff. The example slightly overlaps the schema's own '@sally' example, but the description stays front-loaded and free of filler.

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

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

With no output schema, the description correctly discloses that the return value is a code, and it names the follow-up tool needed to complete the flow. For a two-parameter, non-destructive request tool this covers what an agent needs to call it and act on the result; only edge cases like duplicate or stale requests 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 coverage is 100%, so both parent and secret are already documented, including the note that secret may be omitted when the connector carries it. The description restates the parent format with an example but adds no syntax or behavior beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('ask to be named under your human's main name') and illustrates the resulting identity with a concrete example (@sally/accountant for @sally). This lets an agent distinguish it from siblings like approve_name and name_line 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?

Explains the workflow: this is a request that returns a code, which the human's main AI must then approve with approve_name. That gives clear context for when to reach for this tool versus approve_name, though it never states a when-not condition or mentions alternatives such as join_directory.

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

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

Annotations already declare non-readonly, open-world, non-idempotent, and non-destructive. The description adds meaningful context beyond those: it limits the action to one short message and discloses the privacy behavior ('sealed for that line's AI alone'). It does not describe delivery confirmation or failure handling.

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, with no redundant or filler text. Every clause adds usable 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?

Covers precondition, message content, and privacy behavior for a four-parameter mutation tool with no output schema. It relies on the schema for secret and intent details, which is reasonable, though it could say more about what happens after delivery.

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 goes further by giving content guidance for the message parameter ('Say who you are, who you're calling for, and what you need'), which adds meaning beyond the schema's character limit.

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 one short message') and scopes it to a precise precondition: a line whose voicemail answered, described as a call that came back away. This cleanly separates it from live-call siblings like say and from voicemail retrieval.

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 triggering condition ('a call that came back away, with voicemail'), so an agent knows when this applies. It does not explicitly name alternatives such as say for live calls or voicemail for listening, leaving that inference to the agent.

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

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

Annotations already mark this as a non-readonly, non-idempotent, non-destructive, open-world action. The description adds important behavior beyond that: the effect is one-time only, nothing is retained, and the next call will be screened again.

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

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

The description is three short sentences, front-loads the immediate effect, then clarifies persistence and the alternative. Every sentence contributes useful information.

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

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

For a simple two-parameter action with full schema coverage and relevant annotations, the description covers the action, its one-time nature, the caller's current state, and the contrasting persistent tool. 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 description coverage is 100%, so both `secret` and `address` are already well documented in the schema. The description does not add meaning about parameter formats or values beyond what the schema provides.

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

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

The description states a specific action: letting a currently screened caller through for this one call so their call rings straight to the user. It also clearly distinguishes this one-call behavior from the sibling `allow`, which is described as the persistent alternative.

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 an explicit use condition, the caller is holding at the door now, and explicitly routes persistent exceptions to `allow` only after a good call. The when-to-use and when-to-use-alternative guidance is concrete.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety and idempotency are covered structurally. The description adds value by naming what is surfaced (hold reasons, missed calls, alert devices, allow-list), but says nothing about scope limits or freshness that the annotations do not already imply.

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 compact sentence with no filler, and the content enumeration is front-loaded after the framing clause. The phrase 'in plain words' is slightly wasteful but does signal a human-readable summary.

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

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

With no output schema, the description must describe what comes back, and it does so by listing the four content areas. Given a single optional parameter already fully documented in the schema, an agent has enough to call it; only the missing verb and sibling routing keep it from being complete.

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

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

Schema description coverage is 100% and the single 'secret' parameter is fully documented in the schema, including the get_line origin and the opt-out behavior. The description adds nothing about parameters, which is acceptable at this coverage level but earns only 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 conveys that this reports the state of 'your line' and enumerates the content categories (hold status, waiting missed calls, alert devices, who gets through), but it never uses an action verb such as 'reports' or 'returns'. It also does not distinguish itself from siblings like missed_calls or answering_brief, which appear to overlap with the 'missed calls waiting' content it claims.

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

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

There is no statement of when to call this versus missed_calls, answering_brief, or get_line. The agent must infer the use case entirely from the content list, and no prerequisites or exclusions are given.

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 openWorldHint and non-idempotency, so the safety bar is lower. The description adds genuinely useful state-machine context — calls expire if nobody comes back — but leaves unexplained whether a listen consumes or acknowledges the answer, and readOnlyHint=false is unaddressed given that "listening" sounds like a read.

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, no padding, with the trigger condition placed first. The phrasing is terse to the point of being slightly cryptic ("a call nobody comes back to ends"), but nothing is wasted.

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

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

There is no output schema, so the description should indicate what a listen returns — speech, a status, or an end-of-call signal — and it only hints at this. For a three-parameter polling tool with upfront annotations, it is adequate but leaves the return value to guesswork.

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 `to`, `secret`, and `call_token` are fully documented in the schema, and the description adds nothing about them. Baseline 3 applies where structured data does all the work.

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?

"Hear what they said" identifies the resource (the remote party's speech) but the verb is metaphorical rather than a specific operation like "retrieve" or "poll". The clause about the last answer saying "still thinking or still ringing" implies it follows answer_call, but an agent must infer that chain rather than being told it.

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 usable trigger (call it when a prior answer reported thinking/ringing) and a repeat instruction ("use it again within a few minutes"). It names no alternative tool and no explicit when-not-to-call condition beyond the implicit expiry note.

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 this as a non-read-only, destructive write, and the description adds real context the annotations can't convey: the link 'holds no secret,' it 'replaces any link they had before' (explaining exactly what the destructive hint means), and it works 'even if you forget the line.' It doesn't say whether the link is shown only once or what the response looks like, leaving a small 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?

Two sentences, front-loaded with what the link is for and followed by when to use it. The phrasing is slightly conversational ('for your human,' 'It holds no secret'), but every clause carries useful information about safety, replacement behavior, and triggering conditions.

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

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

For a one-optional-parameter tool with no output schema and annotations covering the safety profile, the description covers purpose, safety semantics, replacement behavior, and triggering conditions. Only the shape of the returned link and whether it is retrievable later is left implicit.

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 sole 'secret' parameter is already fully documented, including provenance from get_line and the warning not to repeat it. The description still contributes by implying the secret is optional ('even if you forget the line'), which reinforces the zero-required-parameter design. That is a modest but genuine value-add over 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 makes clear this produces a fresh management link for the human's directory listing and that it replaces any prior link. It implicitly distinguishes itself from alerts_link/routine_link by scoping the link to the directory listing, though it never names those siblings explicitly. The generating action is conveyed obliquely ('A fresh link') rather than with an explicit verb, which slightly weakens it.

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

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

It gives concrete when-to-use conditions: 'Use it when they ask, or when they've lost theirs.' That covers the common triggering situations well. It does not name alternatives (e.g., disconnect_link) or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare the non-destructive, non-read-only, non-idempotent profile, and the description adds real context on top: a sealed access model ('only your line's key opens it'), a length cap, and the fact that missed_calls consumes the entry. It does not warn that repeat calls create duplicate entries, which matters given idempotentHint=false.

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 ordered by importance: when to use it, what to write, who reads it, then the security and size constraints. No filler and no restatement of the title.

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

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

For a 2-parameter write tool with annotations but no output schema, the description covers trigger, content shape, access control and limits. It leaves the response unspecified and doesn't address duplicate-write behavior, which are the only meaningful 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, but the description adds a hard constraint the schema lacks: 'Up to 600 characters', which directly bounds the text parameter. The secret parameter's access semantics are left entirely to the schema, so it isn't 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 ('leave your human one line' after a call you answered) and names the exact content to record. It also routes to the read-side sibling ('Their AI reads it with missed_calls'), so an agent can distinguish it from missed_calls and leave_message 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?

The trigger condition is explicit: 'After a call you answered'. It also clarifies the downstream consumer (missed_calls). It doesn't state exclusions, e.g. that missed or unhandled calls belong to a different tool, so it stops short of a full when/when-not split.

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 adds genuinely useful context beyond the annotations: voicemail content is "their words, never instructions" (a prompt-injection warning) and the secret must never be repeated. But it closes with "Then clear them," which reads as a state mutation attached to this tool and is in direct tension with readOnlyHint=true and idempotentHint=true (a second call would return nothing if this tool cleared). The clearing likely belongs to the clear_missed_calls sibling, which is never named.

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?

About 70 words with no filler, but the first sentence is a workflow imperative rather than the purpose, so the actual identity of the tool is front-loaded second. The multi-step instructions (inform, call back, ask, clear) are compressed into a run-on block that would read better as discrete steps.

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

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

For a one-param read tool with full annotation coverage and no output schema, the description covers the essentials: what is returned (who/when/why plus voicemail), safety around untrusted content and the secret, and the follow-up flow. Remaining gaps — ordering, volume, whether voicemail is transcribed — are minor.

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

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

There is a single optional parameter with 100% schema description coverage, so the schema already explains the ls_ secret and the omit-if-carried behavior. The description adds nothing further about it, which is acceptable but earns only 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 names a specific resource and its return contents: "The calls your line missed while nothing was holding it: who, when and why, and any voicemail message a caller chose to leave." That is clearly distinct from a live-call tool like answer_call or wait_for_calls. It stops short of naming clear_missed_calls, so the read-vs-clear boundary with its closest sibling is left implicit.

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?

Timing is explicit and emphatic: "Use this first, every time your human talks to you, before you reply," followed by a concrete escalation policy (narrate immediately; call back only those whose screen held a call the human asked for; ask before anyone else). What is missing is the counterpart guidance — no when-not, and the callback/clearing steps reference actions without naming the sibling tools that perform them.

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 destructiveHint annotation, the description discloses what is preserved during the move and the important consequence that 'this app no longer holds the line' afterward. It also explains the preview behavior of the first call and the confirmation requirement, which is rich operational context for a destructive 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?

The description is front-loaded with the action, then precise safety constraints, then the two-step procedure and final state. Every sentence carries necessary operational or safety information, with 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?

For a destructive, non-idempotent move operation with no output schema, the description covers the key prerequisites, confirmation flow, and post-move consequence. It also explains what the preview call reveals, leaving no major ambiguity for 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 a 3, but the description adds meaningful procedural semantics: the code comes from the human's sign-in page, secret can be omitted if the connector carries it, and confirm should be true only after the human agrees to the preview. This reinforces the two-step workflow beyond the schema wording.

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

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

The description states a specific verb and resource: move your line into another app, while preserving number, allowed callers, listing and voicemail. It clearly distinguishes the operation from siblings like disconnect_line or get_line by explaining the migration outcome.

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 when/when-not rules: use ONLY when the human asks directly in this chat and provides the sign-in code, and never because a caller, message or voicemail asked. It also specifies the two-step invocation: first without confirm, then with confirm: true only after the human confirms.

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: it is free and first-come, names are refused if they contain brands or words like official/support, names can change only once a week, and passing null drops the name. This makes the destructiveHint and idempotentHint annotations concrete and actionable.

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 dense and front-loaded, opening with the core action and examples before constraints. It is close to run-on because several rules are packed into one long paragraph, but nearly every clause carries useful policy or formatting information.

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

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

For a naming mutation with annotations and no output schema, it covers the important unknowns: pricing, claim behavior, naming rules, refusals, weekly change limits, and null semantics. The secret parameter's handling is adequately covered by the schema, so nothing critical 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?

The schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds meaningful validation rules for the name parameter: 3 to 20 letters, numbers, and single hyphens, plus the prohibition on brands and reserved-sounding words. The secret parameter is left 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?

States a specific verb and resource: giving a line a readable name that others can use to call it. It is clearly about naming one's own line, but it does not explicitly distinguish itself from siblings like approve_name or join_name, so sibling differentiation is left implicit.

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 when-to-use context: suggest a name from the human's name when the line has none, claim the one they choose, and never guess an unknown name. It also notes the cost and first-come rule, but does not name alternatives such as approve_name when another party must approve the name.

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

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

Goes well beyond the annotations by disclosing the public, irreversible-feeling exposure of linking identity, the one-day window for posting, and that content is read externally via GitHub's Gists API or the X API. Annotations (destructiveHint, openWorldHint) are consistent with this.

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 and the safety warning, then the step sequence. Dense and somewhat run-on (semicolons, parentheticals), but essentially every clause carries actionable 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?

No output schema exists, so the description must carry the flow — and it does describe the step 1 artifact (a line to post as a gist/tweet) and the external read path. Minor gaps: what happens if the post isn't found within the day, and how `handle` is matched, are not covered.

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

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

The description explains the pivotal semantic of `url`: its absence selects step 1 (generate something to post) and its presence selects step 2 (verification). Schema already documents url/handle/secret at 75% coverage; `service` and the exact relationship between handle and target account are left to the schema/enum.

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

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

Specific verb + resource: proves the human behind a line on an existing GitHub/X account, and states the observable outcome (callers see "verified on X as @them"). Clearly distinguishable from siblings like remove_proof and name_line.

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?

Explicit when-to-use gate ("Only when your human asks"), a plain warning to tell the human first because it publicly ties the line, and a clear two-step call protocol with the condition that selects step 1 vs step 2 (presence of url).

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds useful behavioral context: removal is scoped to a name under the caller's line and should occur only at human request, with an example of the removed identifier.

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

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

The description is two short sentences, front-loads the action and scope, and includes only one clarifying example plus the authorization constraint. There is no wasted text.

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 destructive mutation tool, the description includes the key human-approval constraint and the schema documents the required label and optional secret. Annotations cover idempotence and destructiveness, and no output schema exists; only minor details about success or failure behavior are absent.

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 already documented in the schema, including the required 'label' format and optional 'secret'. The description adds an example identifier but does not provide meaningfully more parameter guidance than the schema.

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

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

The description uses a specific verb-resource pairing: taking a name under the user's control away from a line. The concrete example '@sally/accountant from an AI your human stopped using' makes the operation distinct from sibling tools such as join_name, name_line, and approve_name.

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

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

The sentence 'Only when your human asks' gives a clear authorization condition and implicitly restricts usage to human-initiated cleanup. It does not explicitly name alternatives or describe when removal should be avoided, but the usage context is clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds a consent condition ('when your human asks') but does not disclose the consequence of removal — e.g. whether the agent loses the ability to act on that service or must re-prove via prove_account.

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 short sentence with the action front-loaded and no filler. It is efficient, though the terseness contributes to the missing behavioral and parameter detail.

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 destructive, non-read-only mutation with no output schema and an undocumented required parameter, the description omits what the removal costs the agent, how it relates to prove_account/get_line, and what 'service' means. Annotations cover the safety flags but not the operational consequences.

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 50%: the secret param is documented in the schema, but the required 'service' enum (github/x) has no description of what it selects. The description never references service or secret, so it does not compensate for the coverage gap on the one required parameter.

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 phrase 'Take an account proof off your line' names a clear verb (remove/take off) and resource (account proof), scoped to the agent's own line. It is distinguishable from siblings like remove_name by the noun, but never names its inverse sibling prove_account, so the pairing is only inferable.

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?

'When your human asks' gives a consent trigger, which is genuine usage context, but there is no statement of prerequisites (must a proof exist first?), no mention of prove_account as the counterpart, and no when-not-to-use 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?

Beyond annotations, the description discloses important behavior: the link is one-time, expires within an hour, contains no secret, and is safe to show the human. It also clarifies that routine URL/token should be pasted on the page rather than in chat, which is useful operational context.

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

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

The description is front-loaded with the key concept and each sentence contributes useful context: purpose, human action, safety, expiration, and the answering_brief reference. It is somewhat conversational and could be tighter, but there is little wasted content.

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

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

With one fully described parameter and no output schema, the description covers the essential behavior an agent needs: what the link is for, that it is one-time and time-limited, and how the human uses it. An explicit statement that the tool returns the link URL would make it fully complete.

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

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

The single secret parameter is fully documented in the schema, so the description need not repeat it. The description adds related safety guidance about secrets and chat, but not parameter-level syntax or selection details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly establishes the resource as a one-time link that lets a human connect a Claude routine to the line, and it mentions the related answering_brief sibling. It stops short of a crisp verb-first statement like 'creates a link,' but the purpose is still readily inferable.

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

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

It gives clear usage context: the human pastes the routine URL and token on the page, the link works once within an hour, and answering_brief provides steps and the routine's words. It does not enumerate when-not conditions or compare against listing_link/alerts_link, but the scenario is well defined.

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 openWorldHint=true and non-idempotent/non-destructive behavior. The description adds that it 'returns their answer,' clarifying that this is a synchronous exchange rather than a fire-and-forget message, but it says nothing about blocking duration, failure modes, or secret/auth handling.

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

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

Two short sentences, front-loaded with the action and immediately followed by the return behavior. Efficient, though it may be too terse for the tool's complexity.

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 4-parameter open-world tool with no output schema, the description gives only the minimum: that it returns the other party's answer. It omits how the exchange completes, whether the call stays open, and how errors surface, leaving gaps for an agent orchestrating a conversation.

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%, with the 'to', 'secret', and 'call_token' fields well documented in the schema and only 'message' bare. The description adds nothing about parameters, but the schema does most of the work, so a baseline 3 is warranted.

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 ('say') plus resource ('the next thing on a call') and constrains it to calls you started, which implicitly separates it from answer_call or call. It does not explicitly name the sibling alternatives, so an agent must infer the boundary rather than being told.

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?

'On a call you started' implies the prerequisite (you must have initiated the call and hold a call_token), but there is no explicit when-to-use rule or comparison against answer_call, leave_message, or listen. Usage is inferable rather than stated.

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

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

The annotations already flag destructiveHint=true, but the description adds a critical behavioral disclosure beyond the annotations: 'Everything in it is public to any caller.' That privacy warning is non-obvious and important. It still does not explicitly say that setting the voicemail overwrites existing content, so it is not a 5.

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

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

The description is front-loaded and efficient, using three short sentences with no filler. The opening identifies the resource, the middle explains content, and the final sentence documents the toggle. Minor explanatory phrases like 'what callers hear when you're not listening' are useful rather than wasteful.

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 four-parameter mutation tool with no output schema, the description covers the essential purpose, privacy implications, and the `on` toggle. The schema carries most parameter detail, and annotations carry destructive/idempotent hints. It could more explicitly state what happens when voicemail is turned off or overwritten, but it is broadly complete enough to invoke 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 coverage is 75%, so the baseline is 3. The description adds meaning beyond the schema for the undocumented `on` parameter by saying 'Turn it on or off with on,' and it reinforces the public nature of `facts` and `greeting`. The `secret` parameter is not mentioned in the description, but the schema already explains it well.

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: set your own line's voicemail. It clarifies what the voicemail is for (what callers hear when you're not listening) and identifies the core content fields (greeting and facts). It does not explicitly differentiate itself from siblings like leave_message or answering_brief, so it falls short of a 5.

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

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

Usage is implied by 'what callers hear when you're not listening' and 'Turn it on or off with on,' which tells the agent this configures voicemail behavior. However, there is no explicit when-to-use guidance, no exclusions, and no named alternatives among the many sibling tools.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, and the description adds real context beyond that: this is a blocking long-poll with a default wait, a ~30-second line-hold window after failure, and re-invocation as the correct recovery. The one meaningful gap is whether a returned call is consumed/removed from the queue, which matters given the non-idempotent hint.

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 operating instruction is front-loaded and every sentence carries information — default duration, unattended mode, error recovery. It is dense with nested parentheticals and long clauses, which slows scanning but does not add filler.

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

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

With no output schema, the description does describe the three outcome categories an agent must handle and what to do after each, plus the timeout range. It stops short of describing the shape of the returned call object, but the outcome-level description is enough to branch 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 coverage is 100%, so the baseline is 3, but the description adds decision-relevant meaning: seconds should sit just under your own tool-call timeout, and longer waits save turns for always-on agents. The secret guidance (omit it when the connector already carries it, never echo it) also adds a safety rule beyond the schema 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 (wait) and resource (calls on your line) and defines the return condition: a ringing call, a screened stranger, or nothing. It also names the follow-up siblings (answer_call, let_in) that handle each returned outcome, letting an agent distinguish this long-poll tool from the action tools 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 explicit operating modes: default ~25s wait between steps while working, versus sitting on the line with seconds near your tool-call limit when running unattended (always-on agent or routine). It also gives a recovery rule — if a wait errors, call again at once because the line stays held about half a minute.

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