NodNod

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

Annotations only declare that this is a non-read-only, non-destructive write, so the description carries the real burden and does: scopes default to the caller's and may never be wider, a 5-key trial ceiling, trial-scope clamping while the owner is unverified, one-time secret return ("store it"), and team-key revocation on leaving the team. These are non-obvious consequences an agent must know before invoking.

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

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

Front-loaded with the action, then constraints, then the one-time-secret warning — every sentence carries information. The semicolon-chained space/team clause reads slightly run-on and could be split, 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?

Given an output schema exists, return shape needn't be explained, yet the description still flags the one-time secret return, which is critical. Trial limits, scope inheritance, and team semantics cover the tool's complexity; only the label parameter goes 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 only 33%, and the description compensates for the two undocumented parameters: it explains the scopes default and the never-wider constraint, and elaborates the "team" value of space beyond the schema's own text. label remains undescribed, though its meaning is self-evident.

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?

"Makes a new key on your own account" states a specific verb and resource with scope (own account), and the narrowing example clarifies the typical intent. It is clearly distinguishable from siblings such as list_keys, revoke_key, and create_nod without opening any schema.

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

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

Gives an explicit use case ("a narrower one for a helper") and conditions: trial accounts capped at 5 live keys, unverified owners cut to trial scopes, and team keys only where teams exist. It stops short of naming alternatives like revoke_key or use_key, but the when-to-use 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), the description discloses real behavioral facts: the new Nod starts private, defaulting applies to omitted parts, and there is a trial quota of 3. It does not mention what the response contains or whether quota exhaustion errors, but the added context is substantive.

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 short clauses, front-loaded with the core action and the required-parameter fact. The telegraphic style and inconsistent quoting (space "team") make it slightly clipped, but there is no filler or wasted sentence.

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

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

For an 11-parameter creation tool with an output schema and near-complete parameter documentation, the description covers the essentials: required field, defaults, privacy posture, quota, and team-space implications. Minor gaps such as error behavior on quota exhaustion are acceptable given the output schema and annotation coverage.

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

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

Schema coverage is already 91%, so the schema carries most parameter meaning; the description adds the useful defaults rule ("parts left out use 'default'") and reinforces the teams-only constraint on space. This goes slightly beyond restating schema text rather than merely duplicating it.

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

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

The opening sentence gives a specific verb and resource ("Makes a new Nod"), immediately distinguishing it from siblings like update_nod, delete_nod, and list_nods. An agent knows exactly which operation this is 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?

It clearly frames creation semantics (name is the only requirement, omitted parts fall back to "default") and adds a concrete gating condition: trial accounts are capped at 3 Nods, and space "team" is teams-only. It does not explicitly route to update_nod for existing Nods, but the create-vs-modify distinction is strongly implied.

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

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

Beyond the destructive and non-read-only annotations, the description explains that removal affects both the account and its page while the Nod's history remains available to the owner. This is useful scope and retention context, though reversibility, restoration, permissions, and behavior for missing or already-deleted IDs remain unspecified.

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-load the operation and then state the important history-retention behavior. There is no filler, and the length is appropriate for a one-parameter deletion tool.

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 deletion with destructive annotations and an output schema, the description adequately covers the core effect and what happens to history. Guidance on obtaining the ID, choosing deletion over updating, and recoverability or authorization would make it more complete, but these gaps do not prevent straightforward 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 sole id parameter has no schema description, and the description never explicitly explains that it identifies the target Nod or where to obtain that identifier. The schema structurally specifies a UUID, but the description adds no parameter semantics to compensate for the 0% 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 states the operation and resource: removing a Nod from the account and its page. The retention detail further clarifies the effect, although there is no explicit differentiation from lifecycle siblings such as update_nod.

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

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

There is no explicit when-to-use guidance, prerequisite, or contrast with update_nod for modifications rather than removal. An agent can infer that deletion is appropriate when a Nod should be removed, but that inference comes from the operation itself rather than dedicated usage guidance.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds modest value with 'right now' (live, not cached state) and 'this key' (scoped to the calling credential rather than the whole account). It says nothing about auth failure behavior or errors.

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 no wasted words, front-loading the most decision-relevant item (owner verification) ahead of secondary fields. Nothing to trim and nothing repeated from the annotations.

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

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

With an output schema present and no input parameters, the description need only justify selection, and it largely does. The remaining gap is behavioral context around authentication state, which none of the structured fields cover.

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 tool takes zero parameters, so there is no parameter semantics to add beyond what the empty schema already communicates. Baseline 4 applies; the description does not need to explain inputs.

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 concrete contents returned: owner verification status, the caller's handle, and the scopes the current key holds. That is specific enough for an agent to distinguish this from get_balance or list_keys. It falls short of 5 only because it never names a sibling or states scope exclusions 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?

Use cases are implied by the content list (check verification, read handle, inspect key scopes), so an agent can infer when to reach for it. There is no explicit when-to-use statement, no prerequisite (e.g. authenticated session), and no named alternative among the 20+ siblings.

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

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

Annotations already declare this a safe, non-destructive, closed-world read, so the description carries a lighter burden. It usefully discloses the dual-unit output and that a zero balance includes an explanatory line, but says nothing about freshness, caching, or when the zero reason is absent — and the existing output schema already documents the shape.

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

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

A single front-loaded sentence with the key unit conversion, so nothing essential is buried. The trailing clause about the zero-balance line is slightly awkward but still earns its place.

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

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

With no parameters, an output schema, and full annotation coverage, the description only needed to explain what the number means and the edge case at zero — both of which it does. The missing piece is disambiguation from sibling read tools.

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 tool takes zero parameters, so there is no semantic gap to close and the baseline of 4 applies. The description correctly implies no filtering or scoping is possible.

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 precisely ("Money available for running Nods") and pins down units and representation, so an agent knows exactly what is read. It stops short of a clean verb+resource statement and never distinguishes this from siblings like get_account or get_usage.

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

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

There is no guidance on when to call this versus get_account or get_usage, which sit in the same account/balance neighborhood. The agent must infer usage from the wording alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond that — no note on behavior for missing/invalid ids, no error semantics, no indication of what a 'Nod' contains.

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?

At four words the text is front-loaded but under-specified rather than concise; it omits the verb and any context. Brevity here reflects a missing description rather than efficient writing.

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

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

An output schema exists, so return values need not be explained, and the tool is structurally simple. Still, for a domain-specific resource ('Nod') the description gives an agent nothing about what is returned or how failures behave, leaving it thinner than the tool's minimal complexity warrants.

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 parameter, id, and the schema already pins it to a UUID format with a strict pattern. The description's 'by id' merely restates the parameter name and adds no meaning about where the id comes from or what happens if it is malformed.

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 'One Nod by id' implies a single-record retrieval keyed by identifier, and the title 'Read one Nod' confirms the read verb. However, the description never states the verb itself and never distinguishes this from list_nods or get_* siblings, so an agent must infer that this fetches exactly one record rather than a collection.

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

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

There is no guidance on when to use this versus list_nods or the other get_* tools, and no mention of prerequisites such as needing a valid existing id. The only implicit signal is 'by id', which the schema already conveys.

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

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

Annotations already establish the safe read-only, non-destructive, closed-world profile, so the description's remaining job is to add context. It does indicate the response covers liveness state, a departure reason, and a cost figure, which is useful signal about what the call surfaces. However, it leaves unclear whether the record is a live or historical session and says nothing about auth or permissions.

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?

It is a single short sentence with no filler, which is structurally appropriate for a simple getter. The problem is that the compression comes at the cost of intelligibility: metaphor substitutes for specification.

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

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

An output schema exists, so return values need not be explained, and the tool is simple with one parameter. Even so, the description fails on the one thing it uniquely had to supply — what the id is and what distinguishes this read from get_nod and the session lifecycle siblings.

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 required parameter with zero schema description coverage, and the description never mentions what the 'id' identifies — session id versus Nod id is genuinely ambiguous given the Nod-centric wording. This is exactly the case where the description needed to compensate for the schema gap and does not.

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 is a metaphorical list of returned facts ("whether the Nod is still in the room, why it left, and what it cost") rather than a statement of what the tool does. It contains no verb and never says it reads or retrieves a session record, so the agent must infer the purpose from the name alone. It is also at odds with the title's framing of a 'live' session while describing post-settlement cost.

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 when-to-use guidance and no reference to alternatives such as get_nod, start_session, or stop_session, even though several siblings operate on the same objects. The phrase 'once settled' faintly implies post-session retrieval but not enough to route an agent reliably.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one useful behavioral detail, the 30-day default window, but says nothing about data retention, aggregation timezone, pagination, or whether results are truncated.

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

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

A single compact sentence that front-loads the returned metrics and ends with the default window. Nothing is wasted, though the fragmentary phrasing means the reader has to supply the implied verb.

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?

One optional parameter plus an existing output schema means the description needn't explain return shape, and it correctly covers the default. The remaining gap, when to prefer this over get_balance or get_account, is a usage-routing issue rather than a completeness failure.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning, and it does: 'days' is the lookback window measured in days and defaults to 30. It does not mention the schema's maximum of 90 or the minimum of 1, so the constraint still lives only in the schema.

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

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

The description names the resource concretely: API call counts broken down by operation and send counts broken down by target. It is clear what data the tool exposes, but it uses a noun phrase with no action verb and never distinguishes itself from siblings like get_balance or get_account, which likely also report aggregate metrics.

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

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

There is no guidance on when to call this tool instead of get_balance, get_account, or other reporting siblings, and no stated preconditions. The agent must infer the use case purely from the metric names.

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, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds genuinely new context that most callers will get an empty list, which prevents an agent from misreading an empty result as an error. It does not cover ordering, pagination, or the shape of returned faces, but the output schema exists to carry that.

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

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

Two short sentences with no padding, and the useful caveat is front-loaded. However, the trailing 'see "note"' fragment is an unfilled template placeholder that reads as broken text and weakens an otherwise tight definition.

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

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

With an output schema present and zero parameters, the description only needs to convey scope and the expected-empty behavior, which it does. The unresolved cross-reference to a nonexistent 'note' leaves the agent without the advertised alternative path, so the definition is not fully self-sufficient.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly implies the result set is scoped implicitly by account rather than by any input.

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

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

The description names a specific resource ('the photoreal Anam avatars') and a specific scope ('on NodNod's own account that this account may use'), which clearly separates it from the many nod/key/session siblings. The listing verb is only implicit, and the pointer to "note" is a broken cross-reference that muddies rather than sharpens the purpose, 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?

It gestures at an alternative ('For an avatar on your own Anam account, see "note"'), which implies a when-not-to-use case, but the reference target is unresolved gibberish — no sibling tool is named, so an agent cannot actually follow the routing. The parenthetical '(most accounts: none yet)' does tell an agent when this tool is relevant, which lifts it above bare minimum.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to argue safety. It instead adds genuinely non-obvious behavior: revoked keys are included in the listing, secret values are never returned, and results carry a prefix plus an is_this_key flag identifying the credential being used. The only gap is that magnitude, ordering, or pagination of the key list is not mentioned.

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 filler, and the scoping fact (live and revoked) is front-loaded before the disclosure about secrets. Every clause carries distinct information about what the caller will and will not see.

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?

This is a zero-parameter read with full annotation coverage and an output schema, so the description only needs to set scope and behavioral expectations — which it does, including the important caveat that revoked keys appear and secrets are withheld. Nothing an agent needs in order to call it and interpret the result 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 tool takes zero parameters, so the baseline is 4 and there is nothing in the schema for the description to clarify. The mention of prefix and is_this_key is output-side information rather than parameter semantics, which is appropriate and not misleading.

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 the exact scope of the resource: "Every key on your account, live and revoked," which tells an agent this is a complete enumeration of API keys rather than a filtered lookup. It is clear enough to distinguish from mutation siblings like create_key and revoke_key, though it never explicitly says "list" or names a sibling, so differentiation is by inference rather than statement.

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

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

Usage is implied rather than stated — the agent can reasonably infer this is how you enumerate keys to find an id before revoke_key or use_key, but no sentence confirms that or excludes alternatives. There are no prerequisites, no exclusions, and no named alternative tool, so the guidance is only adequate for a zero-parameter read.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds one genuine behavioral fact beyond that: soft-deleted Nods are excluded from the result. It says nothing about ordering, pagination, or result size, which are the remaining behavioral questions for a list operation.

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

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

It is a single short fragment with no wasted words, but the brevity is under-specification rather than discipline; one more clause naming the operation and the sibling distinction would cost little and add much.

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

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

The tool is simple (no parameters, output schema present, safety covered by annotations), so the description is close to sufficient. However, for an account-wide list tool it omits whether results are paginated or complete, and omits any routing to get_nod for single-record lookup.

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 tool takes zero parameters and the input schema is an empty object with additionalProperties=false, so there is no parameter meaning for the description to add. Baseline 4 applies.

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

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

The description names the resource (Nods) and a scope condition (not deleted), but it is a noun phrase with no verb and never distinguishes listing from the sibling get_nod. An agent can infer 'list' from the tool name, but the description itself does not state the operation 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?

There is no when-to-use guidance and no mention of the obvious alternative, get_nod, for retrieving a single Nod. The agent is left to infer that this is the bulk retrieval path versus the single-item path.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety and scope are covered. The description adds the genuinely useful behavioral facts that the result is a reference of accepted ids for two other tools and that defaults are included, but says nothing about freshness, caching, or ordering beyond that.

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 fragment with no filler, and the three id categories are stated up front. It loses a point because the fragment lacks a verb and reads awkwardly as a standalone definition, making the agent supply 'lists' from the name.

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

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

With no parameters, an output schema covering the shape of the return, and annotations covering safety, the description only needs to explain purpose and consumers, which it does. A note on whether the values are static or environment-specific would close the remaining gap.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. Its mention of face/voice/brain ids is about return content, not inputs, which is correct for a parameterless call.

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 exact resource: the face, voice, and brain ids accepted by create_nod and update_nod, plus their defaults. That is a specific content statement that separates it from siblings like list_faces or get_nod, though it is written as a noun phrase without a verb, so the 'list' action comes only from the tool 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?

By naming create_nod and update_nod as the consumers of these ids, the description implicitly tells an agent when to call it: before constructing those calls. It never states that guidance explicitly, nor does it contrast with list_faces or clarify whether the values are static, so usage is inferred rather than prescribed.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries real weight here and does so well: it discloses that previously issued codes and links stop working and gives concrete rate limits of 3 per hour and 6 per day. It stops short of saying what happens when the quota is hit or what channel delivery uses.

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 consequence and the limits. Every clause adds information an agent would otherwise lack; nothing is repeated from 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?

An output schema exists, so return values need no explanation, and the invalidation and throttling behavior are covered. The remaining gap is rate-limit failure behavior and any precondition such as an existing owner record, which matters for a state-changing tool with no parameters to signal intent.

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 tool takes no input parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The parenthetical about old codes expiring is the only semantic caveat an agent needs before calling with an empty object.

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: sends a fresh code and link to the owner, with the qualifier that prior codes and links are invalidated. An agent can distinguish this from general reads in the sibling set, though it never contrasts itself with verify_owner, which is the closest ambiguous neighbor.

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

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

Usage is implied rather than stated: you call this when the owner needs a new code or link, and the invalidation note signals it should not be used casually. There is no explicit when-not guidance and no reference to the sibling verify_owner, so the agent must infer the boundary.

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

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

Annotations already flag destructiveHint=true, so the bar is lower, but the description adds real context: the effect is immediate, it applies across both REST and MCP surfaces, it is scoped to the caller's own account, and self-revocation is permitted and terminates the caller's own access. The main undisclosed behaviors are whether revocation is reversible and what happens when the id is unknown or already revoked.

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, zero filler, with the most consequential fact (immediate, cross-surface shutdown) front-loaded and the dangerous self-revocation case called out last where it is most salient.

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?

A rich output schema and explicit destructive annotations carry much of the load, and the description covers consequences and eligibility well. However, for a single-parameter destructive tool where the sole parameter is completely undocumented in the schema, the description leaves the agent without any guidance on supplying the id.

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 0% and the single required parameter 'id' is never mentioned in the description. The text refers to 'the key you are calling with' and 'keys on your own account', which gestures at key identification, but an agent gets no confirmation that the parameter is a UUID, nor any guidance on where the id comes from.

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 the concrete effect of the operation: 'The key stops working at once, on REST and MCP.' Combined with the title this makes the verb (revoke) and resource (an API key) unambiguous, and the scope note 'Only keys on your own account' separates it from sibling operations like list_keys or create_key. It never restates the verb 'revoke' itself, relying on the title for that, which keeps it just short of a 5.

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

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

Gives an explicit eligibility constraint ('Only keys on your own account can be revoked') and a clear precondition for the edge case of self-revocation ('make a new key first if you need one'). Missing is any routing hint for how to obtain the key id (e.g., pointing at list_keys) or what to do if the key is already revoked, so it stops short of full when/when-not coverage.

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

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

Annotations only say non-readonly, non-destructive, open-world; the description goes well beyond by disclosing the automatic leak check, that the URL and embed code are returned, the embed_origins allow-list semantics, the one-agent-on-camera limit, the requirement to be in the room first, that the key is vaulted and never shown again, and the verified-owner prerequisite.

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 mode-by-mode structure is front-loaded and every clause carries information, but the semicolon-chained sentences run long and the opening is a fragment ("to \"page\" opens..."), which costs some readability.

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

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

For a 6-parameter, three-mode dispatch tool with an output schema, the description covers selection, prerequisites, side effects, follow-up (stop_session), and key handling. Nothing an agent needs in order to call it correctly is missing, and return values are correctly left to the 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?

With 50% schema coverage, the description compensates well: it maps `to` values to the required companion parameters, explains what embed_origins unlocks, and clarifies that meetingburner_key is supplied once and retained. Only `audience` and `id` go unmentioned, and both are already documented in the schema.

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

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

The description names a specific verb and resource and then breaks the tool's behavior into its three modes ("page", "meeting", "meetingburner_room"), stating what each does. An agent can distinguish the modes without opening the schema, and the personal-page vs in-call distinction 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?

It supplies concrete conditions for each mode: page needs only the id (plus optional embed_origins), meeting requires meeting_url, and meetingburner_room requires a room link plus a one-time meetingburner_key, with the constraint that you must already be in the room. It also routes the reverse action to stop_session. It stops short of contrasting itself with siblings like start_session or test_nod, so it is not a full selection guide.

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?

Well beyond the annotations (which only say not-readOnly, not-destructive, open-world), the description discloses that the key is shown once, that it is live immediately with an enumerated capability set, that exactly one email with a confirm link plus backup code goes to the owner, and that the MCP door auto-attaches the key to the session. These are the non-obvious behaviors an agent needs before calling a mutation that sends mail to a third party.

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 outcome (account plus API key in one call), then the capability state and the verification path — a sensible order. Every sentence carries information, though the five-tool enumeration and the parenthetical '(shown once)' make the first sentence dense; a tighter list would read faster.

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

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

An output schema exists, so return values need no prose, and the description covers ownership, key lifetime, email side effect, and post-verification escalation. The notable gap for a signup tool is collision/idempotency behavior — what happens if owner_email or handle already has an account — which the agent cannot infer and cannot find in the schema.

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

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

Schema coverage is 75%, so three of four parameters already carry schema text; the description reinforces owner_email by framing it as the accountable human who receives the confirm link, which adds intent beyond the format/pattern. But key_label has only a maxLength in the schema and is never explained in the description, and handle/display_name are already covered by schema descriptions. The net added meaning is modest, matching the baseline 3 for high schema coverage.

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

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

The description states a specific verb and resource pair — creates a trial account, returns an API key — and immediately bounds the scope against siblings by naming which tools work with the unverified key (create_nod, test_nod, list_parts, create_key, revoke_key) versus which require verification. An agent can distinguish sign_up from create_key, start_session, and verify_owner without opening another schema.

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

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

It gives clear situational context: open to any agent, works immediately for a defined subset of actions, and full capability (send Nods and spend) only arrives after the owner confirms via link or the agent passes the six-digit code to verify_owner. That effectively routes the agent to verify_owner as the follow-up. It stops short of stating when this should be used versus an existing account path (e.g. get_account or use_key), so no explicit exclusion is 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing billing ('paid from your balance'), the return payload, the agent's opening behavior, and three distinct termination conditions: manual stop, one minute of an empty room, or credit exhaustion. That cost and lifecycle detail is exactly the context an agent cannot get from structured fields.

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

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

Three sentences, front-loaded with the action and the return value before moving to lifecycle rules. Prose is slightly idiosyncratic ('The Nod says it is an AI agent') but every sentence 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?

An output schema exists, so the return values needn't be spelled out, and the lifecycle/billing narrative is a real asset. However, for a billable, state-creating tool, the unexplained 'seconds' parameter and the absence of any note on re-entrancy (starting twice for the same Nod) leave 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 description coverage is 0% and neither of the two parameters is explained. The 'id' parameter's referent (presumably a Nod) is only guessable, and 'seconds' (30-7200) is never defined — it is unclear whether it caps session lifetime or is merely a hint, which directly conflicts with the stated 'leaves when... your credit ends' behavior.

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

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

States a specific verb and resource ('Starts the Nod in a fresh room on our GPU') plus what it returns (room address and a LiveKit pass). This clearly separates it from siblings like get_session, stop_session, and create_nod, which are retrieval, termination, and provisioning respectively.

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

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

Usage is only implied: an agent can infer this is the tool for beginning an interactive voice session, and 'It leaves when you stop it' hints at stop_session. There is no explicit when-to-use statement, no mention of prerequisites (does the Nod need to exist first?), and no guidance on what to do if a session is already running.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and closed-world scope, so the safety profile is covered. The description usefully adds that the call blocks for a few seconds waiting for graceful shutdown and returns final state and cost — real behavioral value. It omits failure modes such as stopping an already-ended session and whether the wait can time out.

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 that front-loads the action, then the waiting behavior, then the return. Every clause carries information and there is no filler.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety hints. Still, for a state-mutating lifecycle call the agent lacks the target-id semantics and error/idempotency behavior, leaving it slightly under-specified.

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 0% and the description never mentions the single required parameter. Critically, it is ambiguous whether 'id' is a session id or a Nod id, and the description's focus on 'the Nod' actively muddies that reading. With one undocumented parameter, the description does not compensate for the schema gap.

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

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

The description states a specific action on a specific resource: making a Nod leave its room, i.e. terminating a live session. It is clearly distinct from start_session without needing to name it, though it never explicitly routes the agent away from get_session when the intent is only to inspect state.

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

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

Usage is only implied by the word 'now' — the agent can infer this is the terminal action on a session already running. There is no guidance on when to prefer get_session, what happens if the session has already ended, or whether repeated calls are safe.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: it is free with a quota of 30 turns/day in trial and 300 after, it works pre-verification, and it exercises only the brain and personality rather than face or voice.

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?

It is front-loaded with the action and return value, then layers in the timing window, history format, quota and scope limitation. Every sentence carries information, though the history parenthetical is dense and slightly interrupts the flow.

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

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

With an output schema present, return values need no explanation, and the description covers timing, cost/quota, history shape and scope limits. The only notable omission is that the id parameter is never explicitly identified as the Nod's id, and history is not tied to the schema's 24-item cap.

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 0%, so the description must carry parameter meaning, and it does for the hardest one: history is explained as earlier turns, oldest first, each with role user or assistant and a field named text, not content. The id and text parameters are left to obvious inference, which is a minor gap.

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

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

The description states a concrete verb and resource: it sends one message to a Nod and returns its answer, using that Nod's name, personality and brain. The final sentence separates this from the room-based face and voice path, which helps distinguish it from send_nod, though it never names that sibling outright.

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

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

It gives a clear usage window: works right after create_nod, before the owner verifies, and is meant for testing a short conversation via the history array. It lacks an explicit 'use send_nod instead when...' routing statement, so the alternative is only implied by the face/voice contrast.

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

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

Annotations only declare the safety profile; the description adds substantial behavior beyond it: test-mode only, the 4242 test card, the owner-mediated payment flow, the delay before credit lands, and two named failure modes with reasons. That is exactly the context an agent needs to act without surprises.

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 what the tool returns, then the caller's obligation, then the pack/price semantics, then failure states. Dense but every clause carries information; the long compound sentences could be split for readability.

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

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

An output schema exists, so return values need no elaboration, yet the description still covers the notable outcomes (not_live, forbidden with reason). For a single-enum-parameter tool with an owner-authorization prerequisite, nothing material is missing.

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

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

Schema coverage is 100% and the single enum is already documented, so the baseline applies, but the description still adds real meaning by contrasting amount_usd (credit added) against price_usd (what the owner pays, possibly less on a paid plan) — a distinction easy to confuse.

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 — answers a Stripe TEST-mode Checkout link for one credit pack — and enumerates the three packs with their dollar values. An agent can immediately distinguish this from siblings like get_balance or get_account.

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 about the caller flow: this tool does not pay, the link goes to the owner, and the credit shows up in get_balance a few seconds later — which implicitly routes follow-up checks to that sibling. Preconditions (confirmed owner) and non-success states (not_live, forbidden) are spelled out, though no sibling is explicitly named as an alternative.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, which leaves the update semantics unexplained. The description fills that gap by stating that only supplied fields change, so omitted fields are preserved, and that is_paused=true halts sending entirely — both non-obvious behaviors an agent needs before calling. It stops short of disclosing permission requirements, whether slug changes break existing page addresses, or whether a paused Nod still answers reads.

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

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

Two short sentences with no filler, and the partial-update rule is front-loaded where the agent will read it first. The second sentence is narrowly scoped to one parameter, which makes the overall length feel slightly lopsided but not 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?

The tool has 12 parameters, annotations that cover only safety hints, and an output schema, so the description carries moderate burden. It covers the essential partial-update contract but omits what the caller gets back, what happens to a Nod when paused (still listed? still reachable?), and whether slug edits invalidate the existing page address.

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 75%, so most parameters (face, brain, voice, slug, abilities, personality) are already documented. The description adds one critical cross-parameter rule — omitted fields are untouched — but singles out is_paused for explicit explanation while the remaining undocumented parameters get nothing extra.

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 never states what a Nod is or that this edits an existing one; that verb+resource information lives only in the name and title. "Changes only the fields you pass" conveys update semantics rather than purpose, so an agent gets partial-update behavior but not a standalone statement of what the tool does.

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

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

There is no guidance on when to use this versus create_nod (for new Nods) or get_nod (for reading), and no mention that id is required or that a Nod must already exist. The only usage-adjacent hint is the is_paused instruction, which is parameter-level, not tool-selection 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?

With no annotations, the description carries the full burden, and it does disclose the most important trait: the key persists for the remainder of the connection rather than applying to one call. It does not say what happens on an invalid or malformed key, whether a previously set key is overwritten, or whether the key is bound to the session. Those gaps matter for a state-mutating credential 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?

Two short sentences, front-loaded with the condition and the effect, with zero filler. The exclusion about sign_up is placed where an agent will read it before deciding to call.

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 tool this covers the decision and the durable effect of the call. It falls short only on failure behavior and overwrite semantics, which an agent would want before re-using this on a connection that may already have a key.

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

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

Schema coverage is 100% and the schema already documents the single parameter, including the 'nod_sk_' prefix. The description adds only provenance (the key came from sign_up or create_key), which is mildly useful but not beyond what the structured fields imply. 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 states a specific action and effect: pass an existing NodNod API key here once and 'the rest of this connection uses it.' It also names the sibling tools that produce such keys (sign_up, create_key), so an agent can place it relative to them. It is slightly less crisp about whether it attaches, validates, or replaces a key, which keeps it below a 5.

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

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

It gives a clear positive condition ('if you already have a NodNod API key from an earlier sign_up or create_key') and an explicit exclusion ('not needed right after sign_up'). What it leaves implicit is the inverse route: if the agent has no key, it should go to sign_up or create_key instead of calling this.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=false) by disclosing the success effect (trial ends, key can send Nods and spend), the failure threshold (five wrong tries closes the code), and the rate limits (10/hour, 20/day per key and account). These are exactly the behavioral facts an agent needs before spending an attempt, and none contradict the annotation profile.

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

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

Front-loads what the tool is, then layers success effect, lockout behavior, rate limits, and the alternative path in short declarative sentences. Every clause is actionable and none 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 single-parameter verification call with annotations and an output schema present, the description covers purpose, side effects, failure conditions, throttle limits, and the alternative verification route. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 0% and the single parameter is only constrained by a ^\d{6}$ pattern, so the description must carry the meaning. It does by stating the code is six digits and comes from the NodNod email that the owner read, giving the agent the source and format; it stops short of saying anything about error shapes for a malformed code.

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

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

States a specific action (pass the six-digit code emailed to the owner) and frames it as 'the backup to the one-click link,' so the agent knows exactly which verification path this is. It also names the sibling paths (resend_owner_letter, get_account) that cover the other cases.

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 when-to-use (owner read the code from the NodNod email), when-not (the owner pressed the link and get_account already shows is_verified true), and the fallback after lockout (call resend_owner_letter). Nothing about routing is left to inference.

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