ZeroWidth Prism

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

Annotations already declare write, non-destructive, closed-world behavior, so the baseline is set. The description adds genuine behavioral context: the mention path 'rings their notification bell', which is a side effect an agent should know about, plus the thread-vs-reply branching. It stops short of noting auth requirements or idempotency.

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 core action and mode selection before the usage example. The closing etiquette line ('never mention someone who didn't ask') is editorializing but arguably still useful guardrail content.

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

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

For a write tool with no output schema and annotations covering safety, the description covers purpose, use case, thread/reply behavior, and mention side effects. Missing pieces are minor (approvalId meaning, mention limits, what a successful post returns).

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

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

Schema coverage is only 43%, so the description is expected to compensate. It meaningfully explains mentionedUserIds (workspace member ids) and rootId (reply target), but leaves approvalId, workspace, entityKind semantics, and body constraints unexplained. Partial compensation warrants a baseline 3.

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

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

States a specific verb+resource ('Posts a comment on a workspace entity') and clarifies the two modes — new thread vs reply when rootId is given. An agent can immediately tell what this does without opening the schema.

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

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

Gives concrete use cases ('leave findings where the discussion already lives', 'a summary on a long thread') that establish when to reach for it. It does not, however, distinguish this from siblings comments_list or comments_resolve, nor state any when-not conditions.

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 safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower, and the description still adds real behavioral content: result ordering (open first, then resolved) and the fact that authors and timestamps are included. It stops short of stating pagination, volume limits, or behavior for entities with no threads.

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

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

Two sentences, front-loaded with the operative fact (what is listed, in what order) before the advisory second sentence. The second sentence is slightly rhetorical ("where disagreement lives before it becomes a decision") but it does convey routing intent, so little is wasted.

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

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

With no output schema, the description compensates by naming the returned content (threads, authors, timestamps, ordering), which is the key information an agent needs. It remains silent on result size/pagination and on empty-result behavior, so it is strong but not 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 67%: workspace is well documented in the schema, entityKind has only a terse "What the thread hangs on" description, and entityId has none. The description says only "one workspace entity," adding no format, valid-value, or relationship detail beyond the schema enum, so a 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?

States a concrete verb and resource ("Lists the comment threads on one workspace entity") and adds ordering detail (open first, then resolved). It implicitly separates itself from the write-side siblings comments_create and comments_resolve through the read verb, but never names or contrasts with them outright, so sibling differentiation is inferred rather than stated.

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

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

"Read this before weighing in on contested work" gives a thematic when-to-use cue, which is more than nothing. However, no alternatives are named (notably comments_resolve or comments_create, the natural next/previous steps) and there is no when-not-to-use guidance or note on whether resolved threads can be filtered out.

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

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

Annotations already flag this as a non-read-only, destructive mutation. The description adds meaningful policy context beyond that: the operation is a reversible toggle (resolve/reopen), and there is a sequencing constraint requiring justification before resolving. It does not state permission/auth requirements or what happens to existing replies, so it stops short of full disclosure.

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 dense sentences with the mechanical fact (what rootId is) front-loaded, followed by the policy. No filler, no restatement of the title.

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

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

For a 4-parameter mutation tool with no output schema, the description covers purpose, when-to-use, and the key parameter. The gaps are approvalId (never explained) and workspace/auth expectations, which matter for a destructive operation, but the core agent decision-making path is well served.

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

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

Schema coverage is only 25%, so the description must carry more weight. It usefully defines rootId (the thread's root comment id) and implies resolved=true/false via 'resolve or reopen', but says nothing about workspace (which the schema does describe) or approvalId (undocumented in both places). Partial compensation for a low-coverage schema.

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

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

The description states a specific verb (sets the resolved state) and resource (a comment thread), and clarifies the ambiguous rootId by equating it to the thread's root comment id. It clearly covers both directions of the operation (resolve and reopen). It does not explicitly distinguish itself from comments_create/comments_list, though the reply-first instruction implies a division of labor.

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

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

Explicit when-to-use rules: resolve only when the human asked or the question is demonstrably settled, and reopen only for new evidence. It also imposes a prerequisite workflow step ('say what settled it in a reply first'), which implicitly routes the agent to comments_create. This is about as prescriptive as usage guidance gets.

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 non-annotation behavior: result ordering ('most-used first') and the fields returned in each mode (tag name + count; kind, id, title, path), but says nothing about result limits or pagination.

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 two modes that matter most before the usage advice. It is efficient, though 'the vocabulary the team already organizes by' is slight editorial padding for an agent-facing 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 no output schema, the description carries the return-shape burden and does so for both modes, which is the key gap an agent would otherwise face. It omits pagination/size limits, the only remaining incompleteness for a browse tool.

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

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

Schema coverage is 100%, so baseline is 3, and the schema already documents omitting the tag. The description goes beyond that by spelling out what each mode actually produces, which clarifies the semantics of the tag parameter's presence/absence rather than just restating 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 description names the resource precisely and separates the two operating modes: no tag lists all workspace tags with usage counts, a tag expands to all items filed under it across every tool. That mode split makes it trivially distinguishable from entity_tags_get and entity_tags_set.

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

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

It gives concrete usage triggers: 'reuse existing labels instead of inventing near-duplicates' and answering 'show me everything about X' when X is a label. It stops short of naming alternatives (entity_tags_get, search_workspace) or stating when not to use it, so it is clear context without explicit routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are batch-scoped to one entityKind and 'Entities the user can't see are omitted', i.e. permission-based filtering of results. It does not describe pagination or the shape of the returned tag set.

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

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

Three tightly packed sentences, front-loaded with the return value before the usage guidance. The gloss 'the labels galleries organize by' earns its place by disambiguating 'tags' in this domain. Slightly dense but no filler sentences.

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

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

No output schema exists, so the description carries the burden of describing the return, which it does at a high level ('returns the tags on a batch of entities'). Combined with the permission-omission note and the id-sourcing guidance, an agent has enough to call it correctly, though the exact tag object shape remains unspecified.

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

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

Schema coverage is 67%: workspace and entityKind are documented in the schema, but ids is not. The description compensates by explaining where ids come from (the kind's list/get tool or search_workspace) and that they belong to a single kind, which is the key constraint linking ids and entityKind. It does not mention the 100-item batch ceiling, which the schema already enforces.

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 ('Returns the tags on a batch of entities of one kind') and immediately distinguishes itself from entity_tags_set, which it names explicitly. An agent can tell it apart from the sibling tag tools 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 strong context: ids come from the kind's list/get tool or from search_workspace, and it should be run before entity_tags_set so the full set is replaced knowingly. It also frames a concrete question it answers ('what is this filed under'). It stops short of naming when NOT to use it versus entity_tags_browse, so it is not a full when/when-not/alternative spec.

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

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

Annotations already declare destructiveHint=true, but the description adds the crucial nuance annotations cannot: that this is a full replacement rather than an append, that an empty list clears tags, and how to avoid accidental data loss by reading first. It also discloses the tag format constraints and workspace-vocabulary preference, which are real behavioral characteristics.

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

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

Three tight sentences, front-loaded with the destructive replacement semantic that matters most. Every sentence carries distinct, non-redundant information: replacement behavior, read-then-merge workflow, format/vocabulary rules, and id sourcing.

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

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

With no output schema, the description does not explain what the call returns (e.g. the resulting tag list), and it does not mention the needs_confirmation/approvalId flow that the schema implies for a destructive operation. Otherwise it is complete: mutation semantics, safety guidance, format constraints, and id sourcing are all covered.

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

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

Schema coverage is only 40%, so the description must compensate, and it does so for the highest-risk parameter: tags format (lowercase/numbers/spaces/hyphens) and replace semantics. It also explains where entityId comes from. It does not explain entityKind's 20 enum values or workspace/approvalId semantics, which the schema carries on its own.

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

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

The opening clause 'Replaces the FULL tag set on one entity' gives an exact verb, resource, and scope, and the parenthetical '(an empty list clears it)' nails the edge case. It is clearly distinguished from the read-oriented siblings entity_tags_get and entity_tags_browse, which it names directly.

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

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

It explicitly states when and how to use it: read current tags with entity_tags_get first, merge, then pass the full list, and warns that the call is not additive. It also directs the agent to entity_tags_browse for vocabulary and to the kind's list/get tool or search_workspace for the id, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two things beyond that: the return payload is the 'full Markdown body' (valuable because there is no output schema) and that no authentication is required. It does not discuss rate limits or caching, hence not a 5.

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

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

Three short sentences with no filler; the core action is front-loaded and the sequencing hint and auth note each carry distinct information. Nothing could be removed without losing content.

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

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

For a single-parameter read tool with no output schema, the description supplies exactly the missing pieces: what is returned (full Markdown body), when to reach for it versus search, and the absence of an auth barrier. Nothing an agent needs to invoke it correctly is missing.

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

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

Only one parameter, and the schema documents it at 100% coverage including accepted slug formats ('compass/api', '/compass/api', 'docs/compass/api'). The description adds nothing about the slug beyond restating it, so the baseline 3 applies.

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

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

States a specific verb (fetch) and resource (full Markdown body of a docs page) plus the retrieval key (slug). An agent can immediately distinguish this from search_docs (search) and list_docs (enumerate) 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?

Explicitly positions itself in a workflow: 'Use this after search_docs when the user needs the complete content of a page,' which names the alternative and the condition that selects this tool. It does not mention list_docs as the other plausible sibling, so it stops just short of exhaustive routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: 'No authentication required.' It stops short of describing pagination or result shape, but that gap is minor for a simple read.

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

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

Two sentences, no filler, and the scoping/workflow guidance is front-loaded before the operational note about authentication.

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

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

With no output schema, the description does tell the agent what it will get conceptually (available pages, their slugs) and how it fits with get_doc. It omits return fields and pagination behavior, which an agent might want, but nothing prevents 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% and the single optional 'product' parameter is already documented with the same example values in the schema. The description repeats the filter semantics and examples rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Enumerate all available docs pages') with scope and an optional filter named upfront. It is clearly distinguishable from sibling reads like get_doc, list_posts, and search_docs.

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 states the use case: 'discover what slugs exist before calling get_doc', which gives the agent a concrete workflow position. It names one downstream sibling but does not contrast against search_docs, which is the closest overlapping discovery tool.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=false, destructiveHint=false, which is thin for a create operation. The description adds two genuinely useful facts beyond them: the call consumes the workspace's field quota, and it may return a needs_confirmation envelope requiring the agent to pause and get user approval.

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 front-loaded sentences: what it creates, its cost, and the confirmation-flow obligation. No filler, and the most consequential operational facts (quota, approval) are stated plainly rather than buried.

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

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

There is no output schema, so the description must carry return behavior, and it does flag the needs_confirmation case; quota consumption is also disclosed. It stops short of describing the success payload (e.g. returned field id), which would fully close the loop for a create tool.

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

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

Schema coverage is 100% with five well-described parameters, including enum values and the workspace-token caveat, so the schema carries the load. The description only re-characterizes originIdea ('the seed') and adds no parameter-level detail beyond what the schema already states, so baseline 3 applies.

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

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

The description gives a specific verb and resource ('Creates a field') and defines the domain concept ('the seed of an exploration canvas'), so an agent knows this instantiates a Prism field rather than mutating an existing one. It does not explicitly name the sibling it differs from (prism_fields_update/get/delete), but the create semantics are unambiguous.

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

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

Usage is implied by the name and the confirmation note, but there is no explicit when-to-use/when-not guidance or routing to alternatives such as prism_fields_update or prism_panels_create. The 'wait for approval' instruction is useful process guidance, not 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds non-obvious behavior the annotations cannot convey: this is a soft delete, it frees the workspace field quota, attached studies are explicitly NOT deleted, and the call may return needs_confirmation. These are exactly the side-effect details an agent needs before invoking a destructive tool.

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

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

Three dense sentences, front-loaded with the action and its scope before usage conditions, then the confirmation protocol. Every clause carries information; no filler or restatement of the title.

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

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

For a destructive, three-parameter tool with no output schema, the description covers the mutation semantics (soft delete), quota effect, non-destructive boundaries (studies survive), id sourcing, and the confirmation round-trip. Nothing an agent needs in order to call it safely is missing.

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

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

Schema description coverage is 100%, so fieldId, workspace, and approvalId are already documented; the description's 'Field ids come from prism_fields_list' largely restates the fieldId schema text. It adds a little value by linking the confirmation flow to approvalId implicitly, but the schema does the heavy lifting, so the baseline 3 applies.

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

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

States a specific verb and resource ('Removes a field and its whole canvas') and immediately scopes the blast radius, so an agent can distinguish it from prism_fields_update or prism_fields_get without opening any schema. It also clarifies that the canvas is removed alongside the field, which is not inferable from the 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?

Gives explicit when-to-use conditions ('user is done with an exploration or one was created by mistake') and names the prerequisite source of ids ('Field ids come from prism_fields_list'). It also prescribes the follow-up action for the needs_confirmation path ('name the field and wait'), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral value by describing the tree's shape (origin node parentId=null, children along named axes) and the per-node attributes returned, which goes beyond the annotation set.

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

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

Three tight sentences, front-loaded with the core payload ('One field's full tree'), followed by structural detail and the downstream-tool hint. No filler, though the parenthetical attribute list is slightly dense.

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

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

No output schema exists, yet the description sketches the returned structure (nodes with id/parent/axis/description/pinned/color/image/desk-research flags plus AI-clustered groups) and how to use the results. Adequate for a read-only lookup, with minor gaps around grouping semantics.

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%: fieldId's origin (prism_fields_list) and the workspace/token rules are fully documented in the schema. The description adds no extra syntax or format detail for these parameters, so the schema carries the load — baseline 3.

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 (Read) and resource (one Prism field's full node tree), then enumerates what a node contains and adds the AI-clustered groups. This clearly distinguishes it from the sibling prism_fields_list (enumeration) and prism_fields_get (field metadata vs nodes).

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 forward-looking guidance: 'Use node ids with the expand / research / study tools,' and the schema notes the field id comes from prism_fields_list. It establishes the context and downstream workflow, though it never states explicit when-not conditions or names a directly competing read tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by describing the returned shape (name, origin idea, node count) and clarifying what a 'field' actually is, which the annotations cannot convey.

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

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

Two tight sentences with zero filler. The scope (which workspace) and resource definition come first, and the pointer to the sibling is appended where it is most useful.

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

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

There is no output schema, so the description carries the burden of indicating the return shape, and it does so explicitly. Combined with the fully documented workspace parameter and the sibling pointer, an agent has everything needed to call this 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?

There is a single parameter with 100% schema description coverage, so the schema already documents the workspace slug and its default/override behavior. The phrase 'in the active workspace' loosely implies workspace scoping but adds no syntax or edge-case detail beyond the schema. Baseline 3 applies.

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

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

Uses a specific verb ('Lists') and resource ('Prism fields'), and disambiguates the resource by glossing it as 'idea-exploration canvases'. It also enumerates what the listing contains (name, origin idea, node count), so an agent can tell it apart from prism_fields_get without opening either schema.

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

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

Explicitly routes the agent to the sibling for detail work: 'Fetch one with prism_fields_get for its nodes', establishing the list-vs-get alternative. It gives clear context but no explicit when-not condition or prerequisites, so it stops just short of a 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered; the description adds real value on top by disclosing that nodes are unaffected by the edit, that passing null reverts the name to the origin idea, and that the call may return a needs_confirmation envelope. It stops short of describing what the confirmation flow requires or whether changes are reversible.

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

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

Three short sentences, front-loaded with the operation and immediately followed by the most decision-relevant constraint (nodes untouched). No filler or restatement of the title.

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

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

For a destructive mutation with no output schema, the description covers scope, the null-revert rule, and the confirmation handshake. Missing details are minor: what triggers needs_confirmation, and what the call returns on success, though the annotation already flags destructiveness.

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

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

Schema coverage is 67%, and the description fills the notable gap: the bare 'name' property has no schema description, and the text explains that null reverts to the origin idea. The needs_confirmation mention also contextualizes the otherwise cryptic approvalId parameter. Visibility semantics are left to the schema's own enum description.

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 (edits) plus the exact editable attributes (name, description, visibility) and scopes the blast radius with 'Nodes are untouched', which cleanly separates it from prism_nodes_update and from prism_fields_create/delete. An agent can identify the operation without opening the schema.

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

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

Implies usage by pointing at prism_fields_list as the source of field ids and by warning that a needs_confirmation envelope may come back, but it never states when to prefer this over prism_fields_create/delete or what preconditions must hold. Usage is inferable rather than explicit.

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

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

Annotations already declare this as a non-readonly, non-destructive, closed-world write, so the bar is lower; the description still adds real value by disclosing that supporting verbatims are carried across as evidence with links back to the study, and that the call may return `needs_confirmation`. It does not explain what happens on that confirmation path, which keeps it out of the top band.

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

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

Three tight sentences, front-loaded with the core action and destination before the nuance. The em-dash flourish ("THE step that turns a finding into workspace memory") is rhetorical rather than informational, but it is brief enough not to cost 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 4-parameter mutation with no output schema and only 50% schema coverage, the description covers the main flow and the confirmation signal but leaves the approvalId/confirmation round-trip and the relationship to the ledger_entries_* siblings unexplained. Adequate, with identifiable gaps.

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

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

Schema coverage is 50%, so the description must compensate, and it partially does: it explains the themeId-vs-summary branch that the schema leaves implicit. However, studyId and approvalId carry no description in either place, and approvalId is plausibly the key to the `needs_confirmation` behavior the description mentions but never connects.

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 precise verb (promotes) and resource (an analysis theme, or the analysis summary by default) and the destination (workspace Ledger as a belief), including what travels with it (supporting verbatims as evidence). An agent can distinguish this from ledger_entries_create or prism_studies_analyze 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?

"use when the user says an insight matters" gives a concrete trigger condition, and the parenthetical about omitting themeId clarifies the branch between theme-level and summary-level promotion. It stops short of naming an alternative tool (e.g. ledger_entries_create) or a when-not condition, so it is clear context without exclusion.

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

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

Annotations cover the safety profile (mutation with destructiveHint=false, openWorldHint=true). Beyond that, the description adds real behavioral detail: the guest needs no account, the transcript persists on the study and feeds the next analysis run, and the call 'May return needs_confirmation'. That last one is valuable but unexplained — the agent isn't told why or what to do next.

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 dense sentences, front-loaded with purpose and return value before the focusPrompt fallback. Every sentence carries information; the only mild drag is the trailing needs_confirmation clause, which is stated without enough context to be fully usable.

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

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

With no output schema, the description correctly takes on return-value explanation and names the invite link plus the needs_confirmation possibility. For a five-parameter mutation tool it is close to complete, but approvalId — likely the input that resolves needs_confirmation — is left entirely undocumented.

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 20% (workspace is the sole documented param), so the description must carry more. It does clarify focusPrompt — briefs the interviewer on what to dig into, otherwise it explores the study's territory — which is genuine added meaning, but approvalId and intervieweeName are never explained, and the plausible link between approvalId and the advertised needs_confirmation response is left for the agent to guess.

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 (creates) plus the resource (a one-on-one AI-led interview on a study) and its output (invite link to forward). It also implicitly distinguishes itself from the similarly named compass_interviews_create by noting the transcript 'never lands in Compass', which is exactly the kind of sibling differentiation an agent needs.

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 makes the use case clear — mint a link you forward to a guest who needs no account — and explains focusPrompt's default behavior when omitted. However, it never states when to pick this over compass_interviews_create, prism_panels_run, or prism_series_launch_wave, which all sit nearby and could plausibly produce research sessions.

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 genuinely useful behavioral detail beyond that: raw transcript is only returned while no memo exists, and inviteUrl is present only for interviews still awaiting a guest. It omits pagination/volume limits, but the conditional data-shape disclosures are real added value.

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

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

A single dense sentence front-loads the resource and then enumerates returned fields. The em-dash clauses are heavy but each carries distinct information, so there is little waste.

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

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

With no output schema, the description does the work of describing return fields (memo contents, transcript conditionality, inviteUrl), which is a real strength. However it leaves studyId undocumented and says nothing about result volume, ordering, or failure modes, so it is only adequately complete.

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

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

Schema description coverage is 50%: workspace is documented in the schema, but studyId has no description. The description only implicitly signals that studyId scopes results ('The study's interviews') and adds no format, ID-type, or defaulting detail to compensate for the 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 name and title establish this as the read/list counterpart for a study's interviews, and the description concretely characterizes what an interview record is ('one-on-one qual conversations'). It does not explicitly say 'list' or differentiate from prism_interviews_create, but the resource and intent are unambiguous.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g., needing a valid studyId), and no routing to alternatives such as prism_interviews_create or prism_studies_get. The agent must infer the call context entirely.

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 it is a non-read-only, non-destructive write. The description adds two useful traits beyond that: it consumes workspace inference credit and may return a `needs_confirmation` state. It does not, however, explain what confirmation entails or what the generated output looks like.

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

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

Two tight sentences, front-loaded with the operation and the axis concept. The 'THE core Prism gesture' framing is mild marketing but does not obscure the information.

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

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

For a generation tool with no output schema and high schema coverage, the description covers the essentials: what it produces, that it costs credit, and that confirmation may be required. A note on the return shape of the variations 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?

Schema coverage is 86%, so the baseline is 3, but the description adds meaning to the `axis` parameter by giving concrete examples ('more visceral', 'for the skeptic', 'stripped to essentials'). It slightly restates the four-way direction enum rather than adding to 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?

States a specific verb (generate variations) and resource (a Prism node) with the scope made explicit: 'along a named semantic axis ... in one of four directions.' This clearly separates it from siblings like prism_nodes_update and prism_nodes_research.

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?

No when-to-use guidance, no prerequisites, and no named alternatives among the many prism_* siblings. The only contextual hint is the credit-cost note, which informs the agent of expense but not selection.

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

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

Annotations already declare openWorldHint=true and readOnlyHint=false; the description goes further by disclosing that 'thorough' runs three angled passes at ~3× the credit, that the run consumes workspace inference credit, and that it may return `needs_confirmation`. That is meaningful cost/mutation context beyond the annotations, though no auth or rate-limit detail is given.

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 purpose, then layers depth behavior, focus guidance, billing, and return signal in dense em-dash clauses. Nothing is filler, though the packing of multiple distinct facts into single sentences makes it slightly harder to skim.

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

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

Covers the output shape (cited market context stored on the node), cost model, and a possible confirmation state, which is good for a tool with no output schema. But with 6 parameters, two required and two undocumented, an agent still lacks enough to call it confidently, particularly around the approval flow.

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

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

Schema coverage is only 33%, so the description must compensate. It does add real meaning for `depth` (three passes at 3× credit) and `focus` (steers the run; generic brief otherwise), but `nodeId`, the required `fieldId`, and especially `approvalId` are left completely unexplained — and the link between `approvalId` and the advertised `needs_confirmation` return is never made.

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: 'web-sourced secondary research on a node's idea — market context with citations, stored on the node.' The node anchoring and storage location distinguish it from generic research siblings, though no sibling (e.g. prism_research_run) is named 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?

Gives clear actionable guidance for parameter choice ('pass focus whenever the user has said what they actually want to know') and explains the depth tradeoff. However, it never says when to pick this node-scoped research over the other prism_research_* siblings — usage is implied rather than routed.

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 and destructiveHint=true, so the mutation profile is covered. The description adds one genuinely new behavioral fact ('May return `needs_confirmation`'), but leaves it unexplained — what triggers it, what to do next, or how approvalId relates — so the added signal is thin.

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, well-ordered sentences with the core action front-loaded; nothing is padded. The final sentence is a dangling fact that would earn more weight if tied to the tool's parameters, but the overall size is appropriate for a small mutation 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 6-parameter destructive mutation with no output schema and 33% schema coverage, the description is too sparse. It omits any explanation of the approval flow implied by approvalId, the required fieldId/nodeId pairing, and the effect of clearing a pin or color — leaving the agent to infer the risky parts.

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% (color and workspace documented), so the description must compensate for fieldId, nodeId, pinned, and approvalId — all undocumented. The description references 'pinned state' and 'color tag' in prose but adds no format, defaulting, or clearing semantics, and never links the dangling `needs_confirmation` mention to the approvalId parameter.

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

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

Specific verb+resource: setting pinned state and/or a color tag on a node, with the useful gloss that pins form the cross-field shortlist. It clearly describes the mutation, though it does not name or distinguish itself from any sibling (e.g. prism_nodes_expand, prism_fields_update).

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, no prerequisites, and no mention of alternatives for tagging/pinning. The one contextual line ('Pins are the cross-field shortlist') clarifies the domain concept of a pin but does not tell the agent when this tool is the right call versus another Prism node operation.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds real behavioral context beyond that: 'Answers already in stay' tells the agent partial results are preserved and 'May return needs_confirmation' warns of a confirmation envelope. It omits what happens if the run is already terminal or whether cancellation is reversible, keeping it short of a 5.

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

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

Three terse sentences, front-loaded with the action and affected states before the preservation note and the return caveat. Every clause carries information; no filler.

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

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

For a destructive mutation with no output schema, the description covers the target states, the side effect on existing answers, and the confirmation-envelope return path that maps to approvalId. Remaining gaps (terminal-state behavior, irreversibility) are minor against annotations that already flag destructiveness.

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

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

Schema coverage is 67%; workspace and approvalId are described in the schema, and runId is self-evident. The description usefully links the needs_confirmation return to the approvalId parameter, adding meaning the schema alone does not, but it adds nothing for runId or workspace, so baseline-range credit 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?

States a specific verb (Stops) and resource (panel run) plus the eligible states (queued, running, paused), so an agent can distinguish it from prism_panel_runs_get and prism_panel_runs_estimate. It stops short of naming siblings explicitly, but the action and scope are unambiguous.

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

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

The enumeration of valid states ('queued, running or paused') implicitly tells the agent when the call applies, and the needs_confirmation mention hints at a follow-up flow. However, there is no explicit when-not guidance, no mention of alternatives, and no prerequisites (e.g., permissions) beyond what the schema carries.

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 bar is lower. The description reinforces this with 'Starts nothing' and characterizes the return value, which is useful added context. It stops short of auth or rate-limit details, keeping it at a solid 4.

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, front-loaded sentences with no filler: purpose first, side-effect guarantee second, usage rule last. Every sentence earns its place.

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

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

For a read-only estimate tool with clear annotations, the description covers purpose, no-side-effects, the calling sequence, and a summary of the return shape. With no output schema it could say slightly more about the estimate's structure, but nothing essential is missing.

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

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

Schema coverage is 67% (panelId, studyId, temperature undocumented), just below the high-coverage baseline. The description adds no parameter-level detail beyond the domain framing of 'a study against a panel'; the fields that drive cost (samples, interviewPeople, budgetUsd) are only explained in the schema itself.

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 (estimate) and resource (panel run cost), and enumerates what the estimate contains (people, model calls, dollars of workspace credit). It is immediately distinguishable from the sibling prism_panels_run, which actually launches the run.

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 names the alternative (prism_panels_run) and the sequencing condition: 'Tell the person the cost before calling prism_panels_run.' It also rules out misuse with 'Starts nothing,' so the agent knows this is the safe pre-flight check.

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 readOnly/non-destructive/non-open behavior, so the bar is lower, and the description still adds real context: the tool returns spend and the run's own analysis, and it carries an important reporting caveat that synthetic answers are never real people. That caveat is not encoded anywhere in the 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 short sentences, front-loaded with the payload, then the routing rule, then the caveat. No filler and each sentence carries distinct information, though the panelRunId/runId naming shift is slightly jarring.

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 read-only tool with no output schema, listing the returned contents (status, progress, spend, analysis) is helpful, and annotations cover the safety profile. The gap is the undocumented runId parameter, which leaves the caller unsure what identifier format to supply.

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

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

Schema coverage is only 50%: the documented 'workspace' param is fine, but 'runId' has no description in the schema and the description does not explain it either. The only identifier mention is 'panelRunId' passed to a different tool, which does not clarify this tool's own required parameter.

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

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

The description enumerates what the tool surfaces about a panel run (status, progress, spend, its own analysis), which makes the resource and payload clear even without an explicit verb. It partially differentiates from siblings by routing numeric results to prism_studies_results, but does not distinguish it from prism_panels_get or prism_panel_runs_estimate.

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 concrete routing rule ('For the numbers, call prism_studies_results with panelRunId'), which is a genuine when-to-use alternative. However it says nothing about when to prefer this over prism_panel_runs_estimate, prism_panel_runs_cancel, or prism_panels_get, so usage is only partially covered.

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

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

Adds substantial context beyond the annotations: the population drawing happens in the background and 'takes a few seconds' (latency/async behavior), the default visibility is workspace-scoped 'unless visibility is PRIVATE', and it 'May return `needs_confirmation`', flagging the approval flow. These are distinct operational traits the readOnlyHint/destructiveHint flags do not convey.

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

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

Three tight sentences, front-loaded with the core action before the caveats, and every clause carries information (timing, visibility default, confirmation). Slightly dense but 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 create tool with a complex nested spec, no output schema, and 33% schema coverage, the description omits the structure of the spec object entirely and never says what a successful call returns (only the needs_confirmation branch). It covers the confirmation flow but leaves the main payload and success return unexplained.

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 only 33%, so the description must carry more weight, and it only clarifies visibility (PRIVATE scoping) and the origin of the spec. name, description, the nested spec fields (seed, size, filters, targets, presentation), and approvalId usage are left to the schema or undocumented.

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 ('Saves a panel from a spec') and ties it to the workflow by naming the sibling prism_panels_draft as the usual spec source. An agent can distinguish this create step from the draft/get/list siblings without opening the schema.

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

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

The parenthetical '(usually from prism_panels_draft)' implies the correct ordering (draft first, then create) and the description points at the confirmation path, giving clear context. It stops short of an explicit when-not clause or naming alternatives for other paths (e.g. prism_panels_run), so it is not a full 5.

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

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

Annotations cover read-only and safe, and the description adds the crucial behavioral fact that nothing is saved, plus that unsupported traits are emitted as 'assumed' with assumedNotes. It also explains poolSize. This is substantial behavior disclosure beyond annotations.

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

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

Front-loads what it produces, then the draft/save behavior, the handoff, and the poolSize definition. No filler, and the most consequential constraint (saves nothing) is stated early.

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

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

For a 2-param read-only draft tool with no output schema, it covers purpose, non-persistence, the next tool to call, and one derived field. It could say more about what the spec's filters look like, but it is sufficient to invoke correctly.

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

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

Schema coverage is 50% and both params are simple. The description explains poolSize (returned size, not an input) and that description is a plain-language audience, but does not document workspace or describe syntax for sizing/filters in the input string.

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

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

Specific verb and resource: turns a plain audience description into a panel spec with filters, size, and assumed shares. It names the sibling prism_panels_create as the next step, so the draft/create boundary is explicit.

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

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

Gives clear context: show the spec to the person, then pass it to prism_panels_create. It does not state when NOT to use the tool or contrast it with prism_studies_draft/standalone variants, but the draft-vs-create handoff is well defined.

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

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

Annotations already establish the safe read-only profile (readOnlyHint=true, destructiveHint=false), so the description sensibly spends its words on the return shape: current version, per-field shares, and flagged assumed fields. That is genuine behavioral context an agent cannot get from the annotations.

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

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

Two tight sentences with the payload description front-loaded before the use case. Nothing is wasted, though it is not maximally information-dense.

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

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

With no output schema, the description carries the burden of explaining what comes back, and it does so reasonably well (version, field shares, assumed-field flags). The main gap is the undocumented required panelId and absent pagination/error behavior.

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

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

Schema coverage is only 50%: workspace is documented in the schema, but the required panelId has no description anywhere. The description adds nothing about parameter format, sourcing, or the workspace override rules, so it fails to compensate for the coverage 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 names the resource ('One panel') and enumerates its payload ('current version and the share of people by every field'), so the agent knows this is a singular-panel retrieval. It contrasts implicitly with the plural prism_panels_list sibling, though it never names it 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?

'Use it to confirm a draw looks like the audience the person meant' gives a concrete purpose, which is more than most getters offer. But it does not say when to prefer this over prism_panels_list or prism_panel_runs_get, leaving alternative routing to inference.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description still adds real context: the visibility scope ('the person can see') and the meaning of the derived 'fit' metric ('how far it sat from people the last time a study had both'). Pagination and result-size behavior are 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 sentences, front-loaded with scope and contents, with the action guidance last. The field list is dense and the parenthetical defining 'fit' is slightly convoluted, 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?

With no output schema, the description carries the burden of describing return values and does so by enumerating name, version, people, status, runs, and fit. The single parameter is handled by the schema. Pagination or ordering behavior for a potentially long list is the only notable gap.

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

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

Schema coverage is 100% and the workspace parameter is fully documented in the schema, so the description does not need to explain it. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema does the heavy lifting.

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 ('Every synthetic panel the person can see') and enumerates the returned fields, which distinguishes it from prism_panels_get, prism_panels_create, and prism_panels_draft 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?

'Reuse an existing panel before drafting a new one' gives a clear when-to-use rule that routes the agent to this tool before prism_panels_draft. It stops short of naming the sibling explicitly or stating when-not to use it (e.g. when a single panel is already known), so it is clear context rather than full alternative 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?

Goes well beyond annotations: discloses credit spend, draft-study restriction, that answers become a labeled synthetic result set never counted as responses, the background/async nature, and the possible needs_confirmation envelope.

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?

Roughly five dense sentences, front-loaded with the core action, then cost, prerequisites, results, and follow-up. Every sentence earns its place 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 background, credit-spending run with no output schema, it covers the full lifecycle (estimate → run → get), the confirmation edge case, and the synthetic labeling. Nothing an agent needs to call it correctly is missing.

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

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

Adds meaning for the 'kind' modes and the interview behavior, but with 70% schema coverage most parameters are already documented. It doesn't explain budgetUsd, approvalId, or workspace beyond what the schema provides, so it is above baseline but not complete.

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

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

States a specific verb+resource ('Starts a background run: every person on the panel answers the study') and distinguishes the two modes (survey answers vs interview sits with the study's interviewer). Clearly distinct from siblings like prism_panel_runs_get and prism_panel_runs_estimate.

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 what to do before ('give the person the estimate from prism_panel_runs_estimate first') and after ('Follow with prism_panel_runs_get'), and notes the prerequisite that it works on draft studies. Names alternatives by their sibling 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, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds real behavioral value by describing the tool as a cross-study rollup and listing the fields it surfaces, letting an agent predict the payload. It stops short of noting pagination or size limits, which keeps it from a 5.

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

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

Two sentences, no waste. The content of the digest is front-loaded in a scannable list, and the usage/routing sentence follows. Every clause earns its place.

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

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

There is no output schema, and the description compensates by enumerating the return fields in detail, which is exactly what an agent needs to know before calling. Purpose, usage, and follow-up routing are all present for a simple read-only tool.

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

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

Schema description coverage is 100% and the single 'workspace' parameter is fully documented there, including token/default-workspace behavior. The description never mentions the parameter, so it adds nothing beyond the schema — the baseline 3 for full 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?

States a specific resource and scope: a cross-study digest covering 'every study with responses,' and enumerates exactly what it includes (title, origin, response count, latest analysis summary, top themes, Ledger insights). It also distinguishes itself from siblings by naming prism_studies_get and prism_studies_results as follow-ups rather than competitors.

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 positions itself as 'the starting point for "what have we learned about X?"' and directs the agent to specific alternatives (prism_studies_get for insights, prism_studies_results for details) on the studies that matter. The when-to-use and when-to-escalate conditions are both spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine substance beyond that: the exact payload composition (markdown brief + cited sources) and a provenance caveat that claims reflect public sources rather than internal company statements.

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

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

Two tight sentences with the return content front-loaded before the citation rule. Every clause carries information, though the Compass citation instruction is arguably closer to another tool's concern and slightly dilutes the core read description.

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

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

With no output schema, the description usefully enumerates what is returned (brief + sources) and flags the epistemic nature of the content. Combined with read-only annotations this is nearly sufficient, though the origins of studyId/reportId and any pagination or size limits are unaddressed.

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

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

Schema description coverage is only 33% (only workspace is documented), so the description should compensate more. It ties 'this report's id' to reportId for citation purposes but leaves studyId completely unexplained and never clarifies the studyId/reportId relationship, adding only marginal meaning.

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

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

States a specific verb+resource ('Read a desk-research report') and immediately says what a single report contains ('One desk-research report in full: the brief (markdown) and the sources it cites'). The word 'One' implicitly distinguishes it from the sibling prism_research_reports_list, so an agent can tell the two apart.

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 downstream usage context (cite sourceKind 'prism_report' with this report's id when placing claims on the Compass map), which tells the agent what to do with the output. However, it never states when to call this versus prism_research_reports_list or where the required ids come from, leaving tool selection to inference.

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

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

Annotations already cover safety (readOnlyHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real value beyond them: result ordering, the exact fields returned, and the status vocabulary (running / ready / failed).

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, no filler: the first front-loads scope, ordering and returned fields; the second handles the handoff to the sibling tool. Every clause carries information.

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

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

With no output schema, the description usefully enumerates the returned fields and status values, which is the main thing an agent needs. It is close to complete for a simple list tool; only the required studyId identifier goes unexplained.

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 50%: the workspace slug is well documented in the schema, but the required studyId has no description anywhere. The prose mentions no parameters at all, so it neither compensates for the studyId gap nor adds format/syntax detail beyond what the schema already gives.

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

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

Specific verb (list) plus resource (desk-research reports on a study) with an explicit ordering guarantee ('newest first'). It names the sibling it complements, prism_research_reports_get, so an agent can distinguish listing from fetching without opening a schema.

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

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

Explicitly routes the agent: use this to enumerate reports, use prism_research_reports_get to 'read one in full'. The when-to-use alternative is clear, though there are no stated exclusions or preconditions (e.g. what happens with no reports or no studyId).

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, openWorldHint=true, destructiveHint=false), it discloses genuinely useful behavior: the call returns immediately while the report runs for a few minutes, it consumes workspace inference credit, it only keeps findings it can quote, and it may return `needs_confirmation`. These are non-obvious operational traits an agent must know.

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 what the tool is and what `focus`/`depth` do, and most sentences carry distinct information. It runs long with several embedded operational asides, but little is pure 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?

There is no output schema, so the description carries the return burden and does so: it explains the async launch, that a report is created, that status becomes 'ready', and how to retrieve it. Combined with the credit and confirmation notes, an agent has everything needed to call 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?

With only 33% schema coverage the description must compensate, and it does for the two decisive params: `focus` (accumulative steering, broad-to-narrow) and `depth` ('thorough' = three passes at ~3× credit). It leaves studyId, title, workspace and approvalId to the schema, but the key semantics are covered.

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+resource ('web-sourced desk research kept as a report on a study, with citations') and ties it to a study, which cleanly separates it from prism_nodes_research, prism_panels_run and prism_research_digest. An agent can tell what this produces and where it lands 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 gives explicit when/how guidance: steer with `focus` (broad sweep first, then narrower runs), use `depth: thorough` for three angled passes, and for company research create a standalone study via prism_studies_draft_standalone and run one report per business area. It also names the follow-up read path (prism_research_reports_get) and the condition (once status is ready).

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

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

Adds substantial behavior beyond the annotations: questions freeze once the first wave fields (an irreversible constraint), scorer requires a metricId (cross-parameter dependency), and the tool may return a needs_confirmation envelope. These are exactly the traits an agent needs and none are in the 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?

Front-loaded with the core purpose, then the immutability warning, then the optional binding and launch alternative. Dense with parentheticals and em-dashes but nearly every clause carries decision-relevant information; slightly long for the payload.

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

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

For a 12-parameter mutation with no output schema, the description covers the two highest-risk facts (question immutability, needs_confirmation flow) and the metric binding. It leaves the success/return shape and scheduling edge cases unstated, but the schema covers the rest adequately.

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 92%, so the schema does the heavy lifting; the description nonetheless adds the non-obvious rule that a `scorer` needs a `metricId` and clarifies what a scorer does. It does not explain interval/dayOfWeek/scheduleTime interactions beyond what the schema already says.

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 ('Creates a research program that fields the SAME instrument on a schedule'), with concrete examples (brand tracking, weekly pulse) and the key distinction that each wave is an ordinary study. This clearly separates it from prism_series_launch_wave and prism_series_update.

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

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

Gives clear usage context: freeze the questions with the user first, optionally bind a Ledger metric + score rule. It names the sibling alternative for on-demand launches ('Waves launch on schedule, or on demand with prism_series_launch_wave'), though it does not state explicit exclusions for when not to create a series.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true. The description adds significant value beyond those annotations: it explains that closing is irreversible and scores/posts to Ledger, that fielding spends credit, and that it may return 'needs_confirmation'. That is genuine behavioral disclosure of cost and irreversibility, though the confirmation flow is only hinted at, not detailed.

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 text is dense and front-loads the primary effect (closes + fields). However, it crams multiple distinct concepts (scoring, Ledger posting, credit spending, irreversibility, schedule semantics, return value) into run-on sentences without clear separation, making it hard to scan.

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 destructive, multi-effect mutation tool with no output schema and incomplete parameter documentation. The description does not explain the confirmation/approval workflow, what happens to active participant chats, or how approvalId ties into needs_confirmation. For a tool with this complexity, the missing parameter and workflow detail is a significant gap.

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

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

Schema description coverage is only 33% (only the 'workspace' parameter is documented in the schema). The description adds zero information about the required 'seriesId' or the 'approvalId' parameter, which is a critical gap since approvalId is presumably central to the 'needs_confirmation' flow. The description must compensate for the low coverage but 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 states a specific compound action: closing the current wave and fielding the next one from the series' frozen instrument. The verb+resource is distinctive and not shared by any sibling, though the product-specific terminology ('wave', 'field', 'frozen instrument') is somewhat opaque without additional domain context.

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?

States a clear condition ('Manual launches don't move the schedule clock') but doesn't map the tool against sibling tools like prism_panels_run or prism_series_create. It mentions a side effect warning that implies careful timing, but doesn't say when to select this over manual panel runs.

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 without the description. The description adds genuine domain context (that a series has cadence, next wave time, and a metric/score rule) and clarifies the series-vs-study boundary, but says nothing about ordering, pagination, or result size.

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 dense but well-ordered sentences: the entity definition comes first, the field list second, and the sibling boundary last. The '(ADR 0031)' citation is the only token that does not help an agent decide or call, so it is near-optimal rather than flawless.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating the fields a series exposes, which is the right move for a list tool. It omits pagination and any note that results may be empty or workspace-scoped, which are minor gaps given the 100%-covered single optional parameter.

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

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

There is a single optional parameter and schema description coverage is 100%, with the workspace slug and its token-dependent required/ignored rules documented in the schema itself. The description adds no parameter meaning beyond that, so the baseline 3 for high-coverage schemas 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 identifies the resource precisely as 'recurring research programs' and enumerates the fields they carry (name, cadence, enabled state, next wave time, wave count, metric/score rule), which lets an agent distinguish it from prism_series_create, prism_series_update, and prism_series_launch_wave. It never states the verb explicitly, so the listing action is inferred from the tool name rather than the text.

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 statement, but the closing line 'Waves themselves are ordinary studies' implicitly routes the agent to the prism_studies_* tools when it wants wave content rather than series definitions. No exclusions, prerequisites, or direct sibling alternatives are named.

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 and destructiveHint=true, so safety is partly covered. The description adds value beyond that: the instrument-editability window, the `invalid` refusal behavior, and the fact that it "May return `needs_confirmation`" — a behavioral detail absent from annotations. It does not discuss auth requirements or the reversibility of destructive changes.

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 dense paragraph, but it is front-loaded with the core action and each clause carries distinct information (pause/resume, cadence, name, instrument lock, id source, confirmation). Nothing is wasted, though the run-on semicolon structure is slightly harder to scan than a broken-out list.

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 14-param mutation tool with no output schema and 50% schema coverage, the description covers the essential behavioral context an agent needs: the instrument lockout, the id source, and the confirmation flow. Remaining gaps — metricId semantics and consequences of destructive edits — are minor against annotations that already flag destructiveness.

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 only 50% schema description coverage across 14 params, the description compensates well by grouping params to effects: enabled false/true for pause/resume, interval/scheduleTime/scheduleTimezone/dayOfWeek as cadence movers, and questions/scorer as the instrument. metricId and adaptiveFollowUps are left largely or wholly unexplained, which keeps it below a 5.

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

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

The description opens with a specific verb+resource ("Edits a series") and then enumerates exactly what is editable: enabled (pause/resume), cadence params, name, follow-up/auto-analyze settings, and the instrument. It also references the sibling prism_series_list for id sourcing and points to creating a new series when the instrument is locked, so an agent can tell it apart from prism_series_create and prism_series_launch_wave.

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

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

It gives an explicit when-not rule: the instrument (questions/scorer) is editable only while no wave has fielded, after which the server refuses with `invalid` and the correct move is a new series. It also tells where series ids come from. It stops short of naming alternatives for the pause/resume/cadence paths, leaving those as 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?

The description goes well beyond the destructiveHint=true annotation: it discloses async server-side execution, the incremental read scope, the polling handshake with prism_studies_get, credit consumption, and two non-obvious return states (upToDate no-op, needs_confirmation). No contradiction with the mutation-oriented annotations.

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

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

Front-loaded with the action and its incremental nature, then layers the async/polling contract and edge cases without a wasted clause. Dense but every sentence carries operational value.

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

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

With no output schema, the description carries the full burden of describing return behavior and does so thoroughly (phase, upToDate, needs_confirmation) plus the async completion protocol and cost implication. An agent has everything needed to invoke and correctly follow up.

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 50%, with workspace and reanalyzeAll documented in the schema while studyId and approvalId are undocumented everywhere. The mention of needs_confirmation implicitly gestures at the approval flow but the description adds no direct semantics for those two parameters, so it only partially compensates.

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 ('Kicks the theme analysis') and immediately qualifies the scope as incremental, so an agent knows exactly what work is triggered versus a full re-read. It is distinguishable from siblings like prism_studies_get and prism_studies_results.

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 concrete follow-up guidance: it returns immediately, so re-read prism_studies_get and poll until insights stop reporting an active run. It also flags upToDate:true as a healthy no-op and warns that needs_confirmation may be returned. It stops short of explicitly contrasting incremental mode against the reanalyzeAll parameter 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?

Goes well beyond the read-only annotations: it discloses the test statistics (Welch t / two-proportion z) at 95%, the 30-response floor, and the exact vsRest value set including not_tested. The explicit warning never to present not_tested as 'no difference' is high-value interpretive guidance an agent could not infer from schema or annotations.

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

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

The core capability is front-loaded and every clause carries substance (output shapes, test types, floor, interpretation rule) rather than filler. It is dense and somewhat run-on, but no sentence is wasted.

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

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

With no output schema, the description carries the return-value burden and does so by naming the vsRest values and the statistics produced. Gaps remain around studyId semantics and what happens if cutBySource and cutByQuestionIndex are both supplied or both omitted.

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 80%, so the baseline is 3. The description clarifies that the cut comes from acquisition source or a single-choice question, reinforcing cutBySource/cutByQuestionIndex, but adds no syntax or format detail beyond the schema and is silent on the required studyId and on conflict between the two cut parameters.

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 ('server-computed banner cut with significance') and details exactly what a target question yields for scale/number vs choice/multi. It never names a sibling such as prism_studies_segments_compute, so differentiation from the other prism_studies_* analysis tools is left implicit.

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

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

Gives a clear when-to-use trigger ('Use this for every "does X differ by Y?" question instead of eyeballing raw rows'), which is stronger than implied usage. It does not, however, name an alternative tool or state when a different prism_studies analysis call would be preferred.

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 destructiveHint=true; the description goes well beyond by naming exactly what is destroyed, describing the interactive needs_confirmation return path, and instructing the agent to surface the study name and response count before proceeding. That is operational behavior the annotations cannot convey.

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

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

Three sentences, each load-bearing: destruction scope first, then the decision rule with its alternative, then the id source and confirmation protocol. Nothing is redundant or buried.

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

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

For a destructive 3-parameter tool with no output schema, the description covers the destructive consequence, the safe alternative, id provenance, and the confirmation return path. An agent has everything needed to call it responsibly.

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 baseline is 3. The description adds genuine meaning by tying the needs_confirmation envelope to the approvalId round-trip and by restating the studyId provenance, giving the agent a workflow context the static schema 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?

States a specific verb and resource (permanently deletes a study) and enumerates the cascading scope — responses, interviews, analysis, share links. An agent can distinguish it from prism_studies_update and prism_studies_get 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?

Explicit when-to-use (a draft that won't be fielded, or a duplicate) and an explicit when-not with a named alternative and the exact parameter to use instead (prism_studies_update closed: true, because it keeps the data). This is the strongest possible routing guidance.

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

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

Annotations only declare the generic write profile (readOnlyHint=false, destructiveHint=false); the description adds substantial non-obvious behavior: the study is created in DRAFT state, respondents never see the idea, generation consumes inference credit, and the call may return `needs_confirmation`. The cost and confirmation disclosures are genuinely useful. It does not explain what `needs_confirmation` requires from the caller, which keeps it from a 5.

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

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

Three sentences, front-loaded with the generation action and its output shape, then workflow and cost. Every sentence carries information. Slightly dense with the parenthetical insert, but 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 mutating tool with no output schema and 25% parameter coverage, the description covers state (draft), cost, and the confirmation return path but leaves the remaining parameter semantics unexplained. Adequate minimum viable coverage, with a clear gap on fieldId/approvalId.

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 only 25% — only `workspace` is documented, while nodeId, fieldId, and approvalId carry no schema description. The description alludes to the node context and hints at an approval flow via `needs_confirmation`, but never explains what fieldId identifies or how approvalId relates to the confirmation return, leaving most parameters undocumented in both places.

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: generates a short study (5-8 questions probing the node's problem space) and creates it as a DRAFT. The phrase 'probing the node's problem space' implicitly distinguishes it from the sibling draft tools (draft_standalone, draft_from_interviews), but no sibling is named, so an agent must infer the routing.

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

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

Provides workflow context — user reviews, previews, and opens for responses from the study page or via prism_studies_update publish — but gives no explicit condition for choosing this over prism_studies_draft_standalone or prism_studies_draft_from_interviews. Usage is implied by the nodeId-driven framing rather than stated.

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

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

Adds real behavior beyond the annotations: it discloses that the draft REPLACES the study's current questions (matching destructiveHint=true) but that 'nothing fields until publish', notes it consumes inference credit, and warns it 'May return needs_confirmation'. These are the kinds of side-effect, cost, and state caveats the annotations cannot express.

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

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

Front-loads the core purpose, then layers prerequisites, optional steer, cost, and the confirmation caveat in dense, non-redundant sentences. No filler.

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

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

For a destructive, credit-consuming, no-output-schema tool, it covers side effects, prerequisites, cost, and the possible confirmation return. The only gap is that the approvalId/confirmation handshake and studyId semantics are not fully spelled out.

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 only 25% (only workspace is documented), so the description carries extra burden. It explains the steer parameter's intent ('biases the instrument, focus on pricing') and implies the confirmation flow tied to approvalId, but studyId and approvalId semantics remain undocumented.

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 (drafts a survey from the study's completed interviews) and qualifies the scope ('GROUNDED in completed interviews'). The 'from_interviews' framing and the note that claims become questions clearly separate it from sibling draft tools like prism_studies_draft and prism_studies_draft_standalone.

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

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

Gives a concrete prerequisite ('Needs at least one completed interview') and routes the agent to prism_interviews_list, plus explains the optional steer with an example. It never explicitly contrasts with prism_studies_draft or prism_studies_draft_standalone, so the alternative-selection guidance is only implied.

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

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

Adds meaningful behavior beyond the annotations: it consumes inference credit (cost), lands on the Studies page in draft state, and may return a `needs_confirmation` signal. The annotations only cover the safety profile (not read-only, not destructive, closed-world), so these operational details are genuine added value, though the consequence of `needs_confirmation` is not explained.

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

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

Front-loads the core action and scope in the first clause, then layers destination, cost, and confirmation behavior. The em-dash aside is dense but the whole block is efficient with no filler sentences.

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

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

For a credit-consuming mutation with no output schema, it covers where the artifact appears, how it's published, and the confirmation edge case. The missing piece is the relationship between the `needs_confirmation` return and the undocumented `approvalId` parameter, which would help an agent complete the flow.

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

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

Schema coverage is 67% — `about` and `workspace` are documented in the schema, and 'anything you can describe in a sentence' loosely reinforces the free-form `about` input. The description adds no syntax or format detail beyond the schema and leaves `approvalId` unexplained, so the baseline 3 fits.

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 ('Generates and creates a DRAFT study') and immediately scopes it with the distinguishing trait 'isn't tied to any canvas node'. This lets an agent separate it from canvas-attached study drafting siblings without opening a schema.

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

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

Gives concrete use cases ('brand tracking, workspace-level research, anything you can describe in a sentence') and points to prism_studies_update for publishing. It doesn't explicitly name the alternative (prism_studies_draft) or state when NOT to use it, but the scope line makes the choice inferable.

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 read (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description earns credit by disclosing state semantics beyond the annotations: insights.activeRun signals an in-flight analysis that must be awaited, and participantUrl is only present when the study is open and a link has been minted. It says nothing about auth/permissions or pagination, so not a 5.

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

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

Three dense but purposeful sentences, front-loaded with the returned payload before the state caveats. Every clause carries information; the parenthetical about activeRun is slightly heavy but justified.

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

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

There is no output schema, so the description carries the burden of describing the return shape, and it does so thoroughly (fields, state, analysis, share link). The main remaining gap is the absence of any guidance on obtaining a studyId or the workspace requirement, which an agent needs before calling.

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?

Only 50% of parameters carry schema descriptions, and the description contributes nothing about either parameter. studyId is undocumented in both schema and description, and workspace (which has schema text) is not clarified further. With the coverage gap on the required identifier, the description fails to compensate.

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 (one study) and enumerates exactly what it returns: questions, response count, open/closed state, stored analysis, and participantUrl. That is far more specific than a generic 'get a study'. It doesn't explicitly differentiate itself from close siblings like prism_studies_results or prism_studies_report, 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?

It gives operational guidance ('wait for it before citing' when activeRun is set, 'cite theme strengths when reporting results'), which implies usage context. However, it never states when to reach for this tool versus prism_studies_list, prism_studies_results, or prism_studies_analyze, so the routing decision 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.

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds value by specifying the returned fields (title, question count, response count, open/closed), but says nothing about pagination, ordering, or authentication needs.

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 zero filler. It immediately anchors the resource, scope, and returned fields, making it appropriately sized for a simple list 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 three-parameter list tool with no output schema and annotations covering safety, the description is serviceable but incomplete. It lists returned fields but omits required-parameter semantics and pagination behavior, which an agent would need for reliable 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 only 33% (workspace is documented; fieldId and nodeId are not). The description implies nodeId through 'attached to one Prism node' but does not explain fieldId or compensate for the undocumented required parameters, leaving the agent to guess their role.

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 ('Feedback studies') and scopes it to 'one Prism node', and lists returned fields. This distinctively separates it from the workspace-level sibling (prism_studies_list_workspace), but the description itself lacks an explicit verb and relies on the title ('List') to convey the action.

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 or when-not-to-use guidance. The scope 'one Prism node' implies the required context, but no alternatives or prerequisites are named, and no routing advice is given relative to prism_studies_list_workspace or other study tools.

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

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

Annotations already carry readOnlyHint/destructiveHint/openWorldHint, so the safety profile is covered. The description adds genuine behavioral context the annotations do not: result ordering (newest first), that all study origins are included, and the shape of each returned row. It stops short of describing volume/pagination behavior, so it is strong but not exhaustive.

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 tightly packed sentences: scope and returned fields front-loaded, then the routing sentence. No filler, and every clause carries selecting 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?

There is no output schema, so the description usefully enumerates what each row contains (title, question count, response count, state, owning field/node/series). Combined with the sibling routing, an agent has everything needed to select and call 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?

With a single parameter at 100% schema description coverage, the schema already explains the workspace slug, default-workspace behavior, and API-key exception. The description adds nothing about the parameter, so the baseline 3 is correct.

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

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

Specific verb+resource+scope: lists ALL studies in the workspace regardless of origin (standalone, canvas-node, series waves), and even names the concrete fields returned. It draws an explicit boundary against prism_studies_list (per-node view) and prism_research_digest (findings view), so an agent can distinguish it without opening any schema.

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

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

Explicitly frames itself as the starting point for 'which studies do we have?' and routes onward: prism_studies_list for per-node, prism_research_digest for findings, prism_studies_get to read one. Both the when-to-use condition and the alternatives are stated outright.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false. Description adds significant value: it runs against inference credit (cost), stores output on the study, and may return needs_confirmation (a possible pause requiring approvalId). This is useful behavioral context beyond annotations. However, it doesn't state whether it overwrites existing narrative or how destructive the operation is.

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?

Well-structured single paragraph, front-loaded with the core action; each sentence adds information (what, source, storage, cost, possible confirmation).

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 no output schema and only 3 params, the description adequately covers the action, source data, storage location, cost implication, and potential confirmation return. Could note approvalId relationship explicitly, but otherwise 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 only 33%, so description must compensate for undocumented parameters. It doesn't mention studyId, workspace, or approvalId semantics. The mention of needs_confirmation implies approvalId is relevant, but doesn't explain the parameter. Baseline 3 is generous given the 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?

Specific verb+resource: 'An AI research analyst writes the report's narrative layer' from the study's computed record, naming the exact components (executive summary, key findings, recommendations). Clearly distinguishes from siblings like prism_studies_analyze (computes the record) and prism_studies_results (returns raw results).

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?

Implies usage by describing the source ('study's computed record (funnel, per-question aggregates, themes, quotes)') and output placement, but does not state when to call this vs prism_studies_analyze or prism_studies_results, nor prerequisites.

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, openWorldHint=false, so safety is covered. The description adds genuine value by disclosing the computed nature of the payload ('numbers you can trust without counting raw rows') and that it emits quality flags such as speeders and duplicate participant ids, giving the agent confidence about data provenance.

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 whose clauses each carry payload information, followed by a one-line directive. It is dense and slightly list-heavy but nothing is wasted and the actionable instruction sits at the end for emphasis.

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 only partial parameter coverage, the description compensates by fully enumerating the return payload, which is exactly what an agent needs to decide whether to call it. Only the studyId parameter's semantics are left implicit.

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

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

Schema coverage is 67% and the description says nothing about studyId, workspace, or panelRunId. The schema itself documents workspace and panelRunId well; studyId is self-evident. Nothing is added beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('a study's computed results' / the Results tab) and enumerates the exact content categories returned: fielding funnel, per-question aggregates, quality flags. An agent can tell this apart from sibling read/report tools like prism_studies_report or prism_studies_cut by the quantitative-aggregate framing.

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 ('ALWAYS use this for quantitative questions about a study') plus an anti-pattern ('never tally answers yourself'), which is real routing guidance. It stops short of naming a sibling alternative for narrative/qualitative questions, so it is clear context without full exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds genuinely new behavior — the null-when-uncomputed state and the fact that the compute sibling requires 30+ responses and 2+ numeric questions. It does not add auth or rate-limit context, so not a 5.

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

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

Two sentences, front-loaded with the core definition of what the resource is and followed by the return shape and the null/compute escape hatch. No filler, every clause earns its place.

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

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

With no output schema, the description carries the return-shape burden and does so: it spells out segment fields, the null case, and where to go when segments are missing. For a simple two-parameter read tool, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is only 50%: 'workspace' is fully documented in the schema while 'studyId' has none. The description mentions no parameters at all, so it does not compensate for the undocumented studyId; studyId is self-evident by name, keeping this at the baseline rather than lower.

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

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

States a specific verb+resource ('the stored k-means segmentation over the study's numeric answers') and enumerates what is returned (named segments with size, share, and distinguishing features). It is clearly distinguished from the sibling prism_studies_segments_compute, which it names 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?

Gives a concrete condition and routes the agent to the alternative: null when nothing is computed yet, and prism_studies_segments_compute is what discovers them (with its 30+ responses / 2+ numeric questions prerequisites). It stops short of an explicit 'use this to read existing segments' statement, but the routing is unambiguous.

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=true), the description discloses the algorithm, the overwrite consequence of recomputing, that naming consumes inference credit, and that the call may return a `needs_confirmation` state. These are exactly the behavioral traits an agent needs before invoking an expensive, mutating operation, and none are recoverable from the 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 dense sentences, front-loaded with the core action, then preconditions, then cost and confirmation caveats. Every clause carries information; 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 tool with no output schema, the description covers inputs preconditions, mutation semantics, cost, and a possible confirmation return. It could say more about what the discovered segments/names look like on return and how approvalId relates to confirmation, but overall it is complete enough to call 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 only 33%: studyId and approvalId carry no descriptions. The description adds no parameter-level meaning, and notably leaves approvalId unexplained even though it ties directly to the `needs_confirmation` flow it mentions. With low coverage, the description should compensate here 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 gives a specific verb and resource: it runs k-means over the study's numeric answers with silhouette-picked k and names the resulting segments. This is far more than a restatement of the name. It does not, however, explicitly distinguish itself from the sibling prism_studies_segments (the likely read/list counterpart), so an agent must infer the compute-vs-read split from the name alone.

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 preconditions are stated: 30+ responses and 2+ numeric questions are required, and recompute overwrites existing results. That is real when-to-use context. It stops short of naming an alternative tool or an explicit when-not-to-use case, so it lands just below the top band.

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 destructive/openWorld/not-readOnly; the description adds substantive behavior well beyond them — publish is one-way and starts working the participant link, questions is a whole-replacement that is LOCKED once responses exist (server refuses with `invalid`), null semantics for endChatFocus/completionRedirectUrl/autoAnalyzeTarget, and the possible `needs_confirmation` return. This is rich operational context.

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

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

Front-loads the publish semantics and then moves through the edit surface efficiently; nearly every clause carries information. The dense parentheticals make it slightly hard to scan but nothing is gratuitous.

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

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

For a 12-parameter, multi-purpose mutation tool with no output schema, the description covers the impactful fields and the locking/confirmation behaviors an agent must know. Coverage of workspace and approvalId is thin, but the structured schema fills that gap, keeping it close to 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?

With only 33% schema description coverage, the description carries much of the load and does so well: it explains what questions replaces, that it needs prism_studies_get for shape, the null-clears behavior for several fields, and endChatEnabled+endChatFocus pairing. It leaves workspace/approvalId unexplained, but workspace is covered by the schema itself.

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 (a study) and enumerates the concrete mutations it performs: publish, close/open, edit title, replace questions, set adaptive follow-ups, closing chat, redirect URL, and auto-analyze target. It also routes the agent by naming siblings prism_studies_get and prism_studies_list_workspace, so it is distinguishable from the read/list tools.

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

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

It gives real when-to-use guidance: 'read prism_studies_get first', the LOCKED-once-responses rule with the explicit answer 'a new study', and where ids come from (prism_studies_list_workspace). It does not, however, contrast this with prism_studies_draft or explicitly state when not to use update at all, so it stops short of the top tier.

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

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

Annotations already declare readOnly, non-destructive, closed-world, so safety is covered. The description adds real value beyond them by describing aggregate content (response counts, theme counts, desk-research presence) and a scope caveat that interviews are now study-level. It omits pagination/limits, which is a minor gap for a list tool.

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

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

Front-loads the returned content before the caveat and the usage directive, so an agent gets the gist on the first clause. Two nested parentheses make it slightly dense, 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?

With no output schema, the description carries the burden of explaining return shape and does so concretely (studies, response counts, theme counts, desk-research flag). Combined with rich read-only annotations, it is nearly complete; only pagination and result limits are unaddressed.

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

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

Schema coverage is 100%, so subjectId, subjectType, and workspace are fully documented in the schema itself. The description only implies the subject is a Prism node, matching the enum, and adds nothing on workspace scoping. Baseline 3 is appropriate when the schema does the heavy lifting.

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 resource and scope ('Cross-instrument findings for one subject') and enumerates the payload an agent gets — attached feedback studies with response and theme counts plus desk-research existence. It also disambiguates from a sibling by name ('Interviews are study-level now — read them per study with prism_interviews_list').

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 ('THE PLACE TO LOOK before proposing new research: cite what already exists') and routes one class of question away to prism_interviews_list. Both the selection condition and an alternative are spelled out rather than inferred.

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

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

Adds real value beyond the annotations by disclosing that no authentication is required and that the corpus is public — something readOnlyHint/openWorldHint do not convey. However, it says nothing about result ordering, pagination, or behavior when nothing matches, leaving meaningful behavioral gaps for a search 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?

Three short sentences, front-loaded with what it does, then return shape, then when to use it, then the auth fact. Zero 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 two-parameter read-only search with a fully described schema and annotations, this covers purpose, trigger conditions, return fields, and access requirements. Nothing an agent needs in order to call it 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 both parameters are documented inline, so the schema carries the load. The description adds no syntax, ranking, or limit guidance beyond what is already structured; baseline 3 applies.

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

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

States a specific verb and resource (search ZeroWidth product documentation) and scopes the corpus precisely — public product docs, not workspace content — which separates it from siblings like search_workspace, workbench_kb_search, and compass_pages_search 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?

Explicitly enumerates the triggering conditions: questions about a named ZeroWidth product, API behavior, or policy. It never names an alternative tool or a when-not-to-use case, so it stops short of full routing guidance.

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

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

Although annotations already declare readOnly/non-destructive/closed-world, the description adds substantial behavior the annotations cannot express: AND-of-words matching across name, tags, folder names and body text, best-first ranking, per-hit fields (id, kind, path, folderPath, tags, snippet), recursive folderId scoping, and permission-based result filtering ('only what the user can see, and only kinds this token may read').

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

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

Purpose and the 'use it FIRST' rule are front-loaded, and every later sentence adds either query semantics, return shape, or id-chaining guidance. The long enumeration of object kinds is the one place it runs heavy, though it doubles as scope documentation.

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

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

With no output schema, the description supplies what an agent needs about results (fields, ranking, snippet meaning, using folderPath to say where a thing lives) and how to chain ids into workspace_files_read or the kind's *_get tool. Permissions, empty-result handling, and workspace/scope limits are all covered.

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

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

Schema coverage is 80%, but the description still adds real meaning: it explains what the q words are matched against (name, tags, parent folder names, inner text) and gives worked examples ('northwind sow' finds the SOW in the Northwind folder). It also clarifies folderId is recursive, matching the schema, and leaves well-documented kinds/limit/workspace to the schema.

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

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

Opens with a specific verb and scope: 'Finds anything in the workspace in one call', then enumerates the object kinds covered (files, folders, flows, shims, knowledge bases, tasks, pages, datasets, evals, rubrics, reviews, specs, sources, Ledger entries, Napkin artifacts). This clearly separates it from focused siblings like compass_pages_search, search_docs, workbench_kb_search, and rooms_search, which each cover one kind.

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

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

Explicit trigger condition: 'Use it FIRST whenever the user mentions something without saying where it lives', backed by three concrete user-phrase examples. It also gives a recovery procedure when results are empty ('try fewer or different words before telling the user it doesn't exist'), which is when-to-use guidance beyond the happy path.

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