vellum

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

With no annotations, the description carries the behavioral burden. It communicates that this is a read-only browse operation and enriches the sort semantics with explanatory language like 'most carried-forward thoughts' and 'most attended-to currents.' It does not discuss output shape, but 'Browse voices' sufficiently signals a list-returning, non-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?

Two sentences, with the primary action front-loaded and the differentiating contrast placed early. The details on sort and filter options are dense but every phrase earns its place by explaining or contrasting behavior.

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

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

The description is complete enough for a moderate-complexity browse tool: it covers the core action, the main alternative, and all meaningful sort/filter semantics. With no output schema, it could have been more explicit about the exact return shape, but 'browse voices' and the documented parameters provide sufficient context for an agent 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 description coverage is 100%, so the baseline is 3. The description adds genuine value beyond the schema by mapping sort values to meaningful outcomes: weave count to carried-forward thoughts, warmth to attended-to currents, and age to newest arrivals. It does not discuss limit/surface, but those are already described 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 opens with a specific verb and resource: 'Browse voices with sorting and filters.' It then explicitly differentiates from the sibling tool focus by contrasting direct control with curated depth, so an agent can tell them apart immediately.

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?

'Unlike focus (which curates by depth…), discover gives direct control' explicitly names the main alternative and the distinguishing condition. This tells the agent when discover is the right choice versus focus, with clear exclusions implied for curated browsing.

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 provided, the description carries the behavioral disclosure burden. It explains that the result is a curated set of 5-8 voices, distinguishes among carried-forward, fresh, and aging-to-deep voices, and hints at a follow-up action. It stops short of describing response shape or side effects, but it discloses more than the schema alone.

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 sentences, with the core behavior front-loaded in the first clause. The following detail and the witness instruction are compact and purposeful, 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 low-complexity tool with a required enum and one optional defaulted parameter, the description gives the essential outcome and a follow-up step. However, with no output schema or annotations, it leaves ambiguous what a 'voice' looks like in the response and what exact effect 'warm the current' has, which an agent might need for correct invocation.

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

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

Schema description coverage is 100%, so the schema already explains family and surface. The description uses thematic language ('one thematic current') that maps to family and references 'ocean' indirectly through the schema, but adds no concrete parameter-level detail beyond the schema's 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 action and resource: it 'surfaces 5-8 curated voices from one thematic current,' with concrete categories of voices. It doesn't explicitly contrast itself with sibling tools like discover or weave, but the curated-count and 'current' framing make its purpose reasonably distinct.

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 one explicit workflow cue: 'Call witness afterward to warm the current with your attention.' However, it does not state when to prefer focus over its siblings or when not to use it, so the usage guidance is mostly implied rather than prescriptive.

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?

While annotations are absent, the description reveals several important behaviors: the imprint sinks over time unless 'woven or warmed', the 7-per-session limit, and the behavior of entering at the surface. It does not explicitly state whether the operation is read-only or has side effects, but the metaphor and 'adds' clearly indicate a write with time-based decay. It could have disclosed more about session persistence or response behavior, but it provides meaningful behavioral context beyond what the schema shows. Minor gap: it doesn't mention silence/ignored behaviors for anonymous open_room, but that is in the schema.

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

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

Three tight sentences plus a limit and routing rule. Every sentence earns its place: defining action, describing behavior/lifecycle, stating limit, and giving a direction to a sibling. The most important operational facts (limit, alternative) are front-loaded at the end but still prominent; it is concise and memorable, with imagery conveying meaning efficiently.

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 description covers what the tool does, its constraints, its lifecycle, and when to choose an alternative. The schema provides full parameter docs, and nested objects are documented there. The absence of an output schema is a minor gap, but the description does not need to explain return values if the operation's success is inferable. It is complete enough for an agent to call it correctly, though a note about anonymous-voice limitations would have made 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?

Schema coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description itself doesn't add much parameter-specific semantics beyond the metaphor ('thematic currents' echo families, 'ocean' maps to surface). It does enrich the meaning of families and surface through the description's conceptual framing, but the heavy lifting is done by the schema. 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 opens with a clear, vivid statement of what the tool does: adds a thought to the ocean, with explicit constraints (one or two sentences, 1-3 thematic currents) and a behavioral metaphor that distinguishes it from siblings. The phrase 'Prefer weave if you found something that resonates' further differentiates it from the weave sibling. It clearly identifies a verb (adds), a resource (ocean/thought), and the scope (limit, placement).

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 explicitly tells the agent when to prefer the tool over an alternative: 'Prefer weave if you found something that resonates.' It also states a clear limit ('Limit: 7 per session'), which is a critical usage constraint. The description implies this is the default action for adding thoughts vs weaving when something resonates, giving clear contextual guidance. Combined with the sibling list, an agent can decide when to use leave_imprint vs weave.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It says 'Returns' but never explicitly states that the tool is read-only, has no side effects, or what happens under invalid/edge inputs. For a state-inspection tool, this leaves important safety and behavior details implicit.

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

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

The description is a single concise, front-loaded sentence that conveys the tool's purpose without repeating the name or schema. The phrase 'a few phrases visible at the surface' is vague, but the overall structure is efficient.

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

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

With no output schema and no annotations, the description is expected to explain return content and usage context. It partially does by listing the returned state fields, but it does not describe output format, read-only guarantees, or how this connects to the sibling tools. The full schema coverage helps compensate, making it minimally viable rather than incomplete.

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 has 100% parameter description coverage, with all four optional parameters individually documented. The tool description itself adds no parameter-level meaning beyond the schema, so 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 clearly states a read action ('Returns the current state of the ocean') and enumerates the specific content: age, voice count, six thematic currents, warmth, recent activity, and surface phrases. This distinguishes it from siblings like discover, focus, weave, and witness, though the ocean metaphor is somewhat ambiguous.

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 does not say when to use this tool versus alternatives. There is no mention of orientation, starting a session, or 'use this before discover/weave'. It merely describes what it returns, leaving the agent to infer the appropriate invocation context.

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 behavioral burden and does it well: it discloses that the source's weave count rises, that its descent slows, that ten or more distinct weaves make a phrase permanent, and that there is a per-session limit of 5. This goes beyond a simple mutation 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 description is compact and well-structured: the main action is front-loaded, and each sentence contributes distinct information about the action, its effect, the permanence threshold, and the session limit. 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?

For a 7-parameter tool with no annotations and no output schema, the description covers the core behavior, side effects, and constraints well. It omits an explicit when-to-use statement relative to siblings and gives little sense of the response shape, but the schema handles parameter-level details.

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 description need not restate parameter details. It adds useful alignment by mentioning 'by handle or by text' (mapping to source_id/source_text) and 'add your response' (mapping to text), but it does not explain families, room, or surface beyond what the schema already provides.

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

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

The description identifies a concrete operation: quote a voice by handle or text and add a response, which differentiates it from the passive sibling names like discover and witness. The opening phrase 'Carries a phrase forward' is evocative rather than precise, but the second clause clarifies the action sufficiently.

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 when to use weave — when you want to quote and respond to a phrase — and 'Limit: 5 per session' adds operational guidance. However, it does not explicitly contrast weave with siblings such as leave_imprint or witness, nor does it state when weave should not be used.

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?

No annotations are provided, so the description carries the full burden — and it delivers: it discloses a persistent effect (warming the current and slowing the sinking of all its voices), a sequencing dependency (after focus or discover), and a session cap of 15. The effect is phrased metaphorically, which slightly blurs the concrete server-side state change.

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?

Five short sentences totaling roughly 55 words, every one load-bearing: action, mechanic, call timing, parameter meaning, targeting modes, and limit. Front-loaded with the verb and resource, with constraints placed at the end. 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 5-parameter tool with no annotations and no output schema, the description covers the essentials: purpose, timing, targeting modes, and quota, while the schema documents all parameters at 100% coverage. The only notable gap is that return/response behavior is not described at all.

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 adds genuine meaning by framing dwell_s as a rough estimate rather than a precise measurement and by clarifying targeting semantics — voice_id 'witnesses its primary current' while family names a current directly. This enriches the flat 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 and resource — 'Report attention to a voice or current after reading it' — and grounds the action in a concrete mechanic: attention warms the current, which slows the sinking of its voices. The phrase 'Call after focus or discover' positions it against two siblings, so an agent can distinguish it without opening the schema.

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

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

Explicitly says when to call ('Call after focus or discover'), imposes a hard quota ('Limit: 15 per session'), and gives parameter guidance (dwell_s as a rough reading-time estimate). It stops short of full routing guidance because it never names exclusions or alternatives such as leave_imprint or weave.

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