ZeroWidth Prism

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the write/safety profile is covered. The description adds value beyond that by disclosing a side effect annotations cannot express: mentioning users rings their notification bell, with an accompanying social caution. It omits permission/auth requirements for posting.

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 its two modes, then layers usage and mention etiquette compactly. Two sentences, minimal waste, though the trailing 'never mention someone who didn't ask' is advisory padding rather than invocation-critical 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 7-parameter mutation with 43% schema coverage and no output schema, the description covers the social/mention dimension well but leaves the entity-targeting parameters and the undocumented approvalId unexplained, which an agent would need to call this reliably in all cases.

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 must compensate, and it partially does: rootId (reply target), mentionedUserIds (workspace member ids, notification behavior), and body are implied. However entityKind's 17-value enum, entityId, and especially approvalId are unexplained in both schema and description, leaving real gaps.

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

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

States a precise verb and resource ('Posts a comment on a workspace entity') and distinguishes the two modes of operation: new thread vs. reply when rootId is given. It never names its closest siblings (comments_list, comments_resolve), so it stops just short of a 5.

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

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

Gives concrete usage context ('leave findings where the discussion already lives') with two illustrative scenarios (eval result on a debated flow, summary on a long thread). It does not state when not to use it or point to a sibling alternative, so it lacks the explicit routing 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 readOnlyHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: threads are returned open-before-resolved and include authors and timestamps, which shapes how an agent interprets output. It stops short of pagination or volume limits.

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

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

Two sentences with the key facts front-loaded and no redundancy. The second sentence is motivational framing that carries mild value but is slightly softer than a hard routing rule.

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 list tool with no output schema and a mostly documented schema, the description covers ordering, content, and the entity scoping needed to call it. Pagination/result-size behavior 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 67%, and the schema itself handles the workspace slug nuances and the enum list. The description only says 'one workspace entity', adding little beyond the structured fields, so the 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 specific verb (lists) and resource (comment threads on one workspace entity), plus the ordering rule (open first, then resolved) and payload (authors, timestamps). This clearly separates it from comments_create and comments_resolve, which mutate rather than read.

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 second sentence gives a soft situational cue ('read this before weighing in on contested work'), which implies when the tool is useful. However it names no alternatives and gives no explicit when-not or prerequisite guidance, so usage remains inferred 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?

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=false, so the mutation/safety profile is covered. The description adds real behavioral context beyond that: the precondition (a reply explaining what settled the thread) and the reopen semantics. It doesn't clarify reversibility or how the state change affects existing replies, keeping it below 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 tight sentences with no filler; the action and the primary precondition are front-loaded before the reopening clause. Every clause carries decision-relevant 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 small toggle tool with no output schema, the description covers the action, the target, and the conditions well. It leaves approvalId and workspace behavior unexplained, which matters for a destructive write, but overall an agent has enough to act 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 only 25%, and the description compensates for rootId only (root comment id). 'resolved' is implied by resolve/reopen framing, but 'workspace' is documented only in the schema and 'approvalId' is explained nowhere — a notable gap for a mutation tool with an approval parameter.

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

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

States a specific verb (sets resolved state) plus resource (comment thread), and covers both directions — resolve and reopen. The parenthetical 'rootId = the thread's root comment id' disambiguates the target, making it clearly distinct from comments_create/comments_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?

Explicitly gates the action: resolve ONLY when the human asked or the question is demonstrably settled, and reply first explaining what settled it; reopen is for new evidence. This is genuine when/when-not guidance with a required prior step.

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/destructive/openWorld, so safety is covered, and the description adds real behavioral detail: result ordering (most-used first), entity counts per tag, and the per-item fields returned in tag mode (kind, id, title, path). No pagination or size-limit behavior is mentioned, keeping this 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?

Front-loaded and cleanly parallel: 'Without a tag:' then 'With a tag:' then the usage clause. Every sentence carries distinct information with no filler.

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

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

With no output schema, the description correctly carries the return-value burden for both modes, and annotations cover the safety profile while the schema covers both parameters. Nothing an agent needs to select or call this tool 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%, so the baseline is 3, but the description adds meaning beyond the schema by characterizing what each mode of the tag parameter actually returns, turning a bare 'omit to list tags' into the two distinct result shapes. The workspace parameter semantics remain entirely schema-borne.

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 dual operation (list every tag in the workspace, or expand one tag into all entities filed under it) with the exact resource and scope. It is immediately distinguishable from the write-oriented siblings entity_tags_get and entity_tags_set because the browse mode and cross-tool aggregation are spelled out.

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 when-to-use guidance: reuse existing labels rather than inventing near-duplicates, and answer 'show me everything about X' when X is a label. It stops short of naming sibling alternatives or stating when-not-to-use (e.g. versus search_workspace), so it is clear context without explicit 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 and destructiveHint=false, so safety is covered; the description adds the non-obvious behavioral fact that 'Entities the user can't see are omitted,' i.e. results are permission-filtered rather than erroring. It does not mention limits (e.g. the 100-id cap or ordering), but the value-add beyond annotations is genuine.

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

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

Three sentences, all front-loaded: what it returns first, then usage, then the permission caveat. No filler and each sentence carries distinct information.

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

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

With no output schema, the description carries the return-value burden and does state what comes back (tags) and the omission behavior. It leaves minor gaps — tag value format, ordering, and whether unknown ids are silently dropped or error — but nothing that blocks 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 coverage is 67%, so the schema documents most params, but the description adds real provenance for the hardest parameter: ids 'come from the kind's list/get tool or from search_workspace.' That tells an agent where to obtain valid ids, which the bare array 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 with scope: 'Returns the tags on a batch of entities of one kind.' The parenthetical 'the labels galleries organize by' distinguishes tags from other entity metadata, and the named siblings (entity_tags_set, search_workspace) make the boundary clear.

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 usage contexts: 'Use it before entity_tags_set so you replace the full set knowingly, and to answer what is this filed under.' That is a real when-to-use plus a stated alternative. It does not mention entity_tags_browse, the other obvious read-side sibling, so it falls short of fully disambiguating the read alternatives.

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, and the description reinforces this with the replace-not-merge semantics and the empty-list-clears behavior. It does not mention the needs_confirmation/approvalId retry flow that the schema implies, which is the one notable behavioral gap.

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

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

Three dense sentences, all front-loaded with the destructive replace semantics first, followed by workflow and vocabulary guidance. Every sentence earns its place; the parentheticals make it slightly busy but not wasteful.

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

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

No output schema exists, and the description covers destructive semantics, prerequisites, id sourcing, and tag format well enough to invoke the tool correctly. The confirmation/approval retry path is left to the schema field description rather than the tool description.

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%, and the description compensates by documenting the tag character set (lowercase letters, numbers, spaces, hyphens), the merge requirement for the tags array, and the origin of entityId. The workspace and approvalId parameters are only explained in the schema, so coverage is good 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 and resource ('Replaces the FULL tag set on one entity') and immediately clarifies the destructive scope with '(an empty list clears it)'. This cleanly separates it from the sibling readers entity_tags_get and entity_tags_browse.

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 workflow: read current tags with entity_tags_get first, pass the merged list, and warns 'this is not additive'. Also routes to entity_tags_browse for vocabulary reuse and names where the entityId comes from (kind's list/get tool or search_workspace), so the agent knows both prerequisites and alternatives.

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 valuable context by stating 'No authentication required' and specifying the return body as full Markdown, which agents need to know beyond the structured hints.

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 core purpose ('Fetch the full Markdown body...'), followed by usage routing and a salient behavioral note. Every sentence earns its place with no redundancy.

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

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

For a simple one-parameter read tool with full schema coverage and annotations covering safety, the description is complete: it states the return format, the required input type, usage context, and authentication status. 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?

Schema description coverage is 100%, and the single `slug` parameter is fully documented in the schema with accepted formats. The description adds no syntax or format details beyond what the schema provides, so it meets the baseline rather than exceeding 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 ('Fetch'), resource ('full Markdown body of a specific docs page'), and retrieval key ('by its slug'). It distinguishes itself from the search-oriented sibling by positioning as the step after `search_docs` for complete page content.

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 to use this after `search_docs` when the user needs the complete content of a page, which names the alternative and the condition that selects it. It does not state when not to use it (e.g., for listing or metadata), but the context is clear enough for a simple 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 context beyond them with 'No authentication required,' a genuinely useful operational fact for callers, though it says nothing about pagination or result size for a full enumeration.

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 with purpose, routing guidance, and the auth fact front-loaded in order of importance. No filler or repetition of the title.

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

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

For a read-only, single-optional-param listing tool whose annotations cover safety, the description is nearly sufficient. Without an output schema it could note the return shape (e.g. that results are slugs/pages), but the 'slugs' reference largely covers that, so only a small gap remains.

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

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

Schema coverage is 100%, so the schema already documents the single 'product' parameter. The description's example values ('compass', 'legal', 'overview') duplicate the schema description verbatim, adding no meaning beyond it. Baseline 3 applies 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 ('Enumerate') and resource ('all available docs pages') with scope, plus the optional product filter. It names the sibling get_doc and frames itself as the discovery step before retrieval, letting an agent distinguish it from single-doc fetch 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 states when to use it: 'to discover what slugs exist before calling get_doc,' giving a clear dependency flow and naming the alternative. It does not address when NOT to use it or whether search_docs is a better discovery path, leaving a minor gap.

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, closed-world operation. The description adds two genuinely useful behavioral facts beyond that: it consumes the workspace's field quota, and it may return a needs_confirmation envelope requiring user approval. It stops short of describing the created object or idempotency/error behavior.

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 clauses, front-loaded with the core action, with no filler. The em-dash gloss on 'origin idea' and the confirmation warning each carry information; the sentences are tight and easy 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?

With 100% schema coverage and no output schema, the description's main remaining duty is to warn about the non-obvious needs_confirmation response, which it does. Quota consumption and the approval flow are covered; only the return shape and failure modes 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 description coverage is 100%, so all five parameters (including the originIdea seed, workspace slug rules, and visibility enum) are already documented in the schema. The description restates the originIdea concept but adds no syntax, format, or constraint detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Creates a field') and clarifies what a field is ('the seed of an exploration canvas'), which an agent needs since 'field' is ambiguous. This distinguishes it cleanly from sibling read/update/delete field tools and from the adjacent prism_interviews/series creation 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?

The description implies the tool's role (field creation) but never states when to reach for this versus siblings like prism_fields_update or prism_interviews_create, nor covers prerequisites such as required quota or prior approval. Usage is inferable from the verb but not spelled out.

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

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

Annotations already declare destructiveHint=true, and the description adds substantial context beyond them: it is a soft delete that frees quota, node-attached studies survive, and the call may return needs_confirmation requiring the agent to name the field and wait. That is exactly the behavioral detail 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?

Front-loads the core action and scope, then layers caveats and the confirmation flow. Every sentence carries information, though the dash-embedded clauses make it slightly dense to parse.

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

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

With no output schema, the description still discloses the meaningful return state (needs_confirmation) and the confirmation protocol. Combined with full param coverage and safety annotations, nothing needed to call this destructive tool correctly is missing.

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

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

Schema coverage is 100%, so fieldId, workspace, and approvalId are already documented in the schema. The description reinforces the fieldId source and the needs_confirmation/approvalId loop but adds no new syntax or format semantics beyond what the schema provides.

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

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

Names a specific verb and resource ('Removes a field and its whole canvas') and immediately scopes it as a soft delete that frees the workspace's field quota. This is clearly distinguishable from prism_fields_update/create in the sibling 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 an explicit when-to-use ('done with an exploration or one was created by mistake') plus a key side-effect caveat that studies are not deleted. It does not name an alternative sibling for the 'don't delete, deactivate' case, so it stops short of a full when-not/alternatives treatment.

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, so the safety profile is covered. The description adds real behavioral value beyond that: it discloses the returned data shape (id, parent, axis, description, pinned, color, image/desk research), the AI-clustered groups, and the data model detail that the origin node has parentId=null. That is useful structural context with no output schema present.

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 compact sentences, front-loaded with the resource and contents, followed by a practical pointer to downstream tools. Every clause carries information with no padding.

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 values and does so thoroughly. Combined with readOnly annotations covering safety and the schema covering parameters, an agent has what it needs 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?

Schema description coverage is 100%, so both fieldId and workspace are already documented in the schema, including the workspace-token nuance. The description adds only incidental meaning (node ids) and does not expand on parameter semantics. 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 states a specific resource (one field's full node tree) and enumerates its contents, distinguishing it from prism_fields_list and the node-level tools. It falls just short of explicitly naming which sibling it complements at the start, but the picture is clear.

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 hints at the workflow by saying 'Use node ids with the expand / research / study tools,' implying this is a discovery step, but never states when to prefer this over prism_fields_list or prism_nodes_expand. Usage is implied 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value by disclosing the lightweight shape of the return (summary fields, not the full canvas), which tells the agent this is a cheap browse operation rather than a detail fetch.

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 compact sentences, front-loaded with the scope and returned fields, closing with the alternative sibling. 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?

With no output schema, the description compensates by enumerating the returned fields, and annotations cover the safety profile. The one parameter is fully documented in the schema, so nothing an agent needs to invoke this correctly is missing.

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

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

Only one parameter with 100% schema description coverage, so the schema fully documents the workspace slug and its override/ignore rules. The description's mention of 'the active workspace' loosely aligns with that scope but adds no syntax or precedence 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?

States a specific verb and resource ('Lists Prism fields') and even defines the domain concept ('idea-exploration canvases'), then names the exact fields returned. It distinguishes itself from prism_fields_get by noting that the latter provides nodes, so an agent can tell them apart without opening schemas.

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

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

Explicitly routes the agent to `prism_fields_get` when nodes are needed, giving a clear alternative for the deeper-read case. It doesn't spell out a 'when not to use' for listing itself, but the browse-vs-fetch split is adequately conveyed.

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

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

Annotations already declare the write/destructive profile, so the description earns credit for going beyond them: 'Nodes are untouched' bounds the blast radius of the edit, 'May return needs_confirmation' discloses an approval round-trip the agent must handle, and null-reverts-to-origin documents a surprising mutation. It doesn't say whether visibility changes are reversible or what the success response contains.

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

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

Three short sentences, front-loaded with the mutation scope, followed by the constraint (nodes untouched), the id source, and the confirmation caveat. No filler and nothing 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 6-param mutation tool with no output schema, the description covers scope, id provenance, and the confirmation workflow, and annotations carry the safety profile. It leaves the workspace-slug fallback and per-param formatting to the schema, which is reasonable. Nothing critical to calling it correctly is missing.

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

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

Schema coverage is 67%, with the workspace, approvalId, fieldId, and visibility params already well documented in-schema. The description adds meaning the schema lacks: that passing null for name reverts to the origin idea, and that approvalId ties to the needs_confirmation envelope. It says nothing about name/description length bounds, which the schema handles.

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) and resource (field) and enumerates exactly which attributes are mutable: name, description, visibility. That distinguishes it from prism_fields_create/delete/get without needing the schema. It stops short of explicitly routing against those siblings, so a 4 rather than 5.

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

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

Usage is only implied. It supplies two useful preconditions — field ids come from prism_fields_list and the call may return needs_confirmation — but never says when to reach for this tool versus prism_fields_create or prism_fields_delete. No exclusions or 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 cover the safety profile (write op, non-destructive, closed-world), so the bar is lower. The description still adds real behavior: it carries supporting verbatims as evidence with links back to the study, and it flags that the call "may return needs_confirmation" – a non-obvious outcome an agent must handle.

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

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

Three sentences, front-loaded with the action, then the framing/value, then the return caveat. No wasted words; each sentence adds distinct information.

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

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

For a 4-param mutation tool with no output schema, the description covers purpose, side effects (verbatim evidence + study links), and the confirmation outcome. The only real omission is the relationship between approvalId and the needs_confirmation flow, which would round it 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?

At 50% schema coverage, the schema already documents themeId (including the omit-for-summary rule) and workspace, and the description reinforces the themeId fallback. However, approvalId is undocumented in both schema and description, leaving a meaningful gap – the likely tie-in to needs_confirmation is never explained.

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 (promotes) and resource (an analysis theme or, with no themeId, the analysis summary) and names the destination (workspace's Ledger as a belief). This is distinct from any sibling tool – none of the other prism_* tools perform promotion into Ledger memory.

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 usage trigger, and the parenthetical clarifies the themeId-omitted fallback. It lacks explicit exclusions or named alternatives (e.g. research_findings_list), but the trigger condition is clear and actionable.

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

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true); the description goes well beyond that by disclosing where the transcript lands ('stays on the study', 'never lands in Compass'), that it joins the next analysis run, that the guest needs no account, and that it may return `needs_confirmation`. It stops short of auth/permission requirements, rate limits, or idempotency, 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 tight sentences that front-load the action and the returned invite link, then layer the side effects and the optional parameter's behavior. No filler and no repetition of the title.

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

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

For a 5-parameter, no-output-schema mutation with 20% schema coverage, the description covers the return value (invite link) and the confirmation edge case, but the undocumented approvalId and intervieweeName leave an agent unable to judge what those inputs do or whether they are needed.

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% (just `workspace`), so the description must carry the load. It explains focusPrompt well ('briefs the interviewer on what to dig into; omitted, it explores the study's territory') but leaves approvalId, intervieweeName, and studyId entirely undefined, so most parameters remain opaque.

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 one-on-one AI-led interview on a study') plus the concrete return artifact (invite link). This clearly separates it from the sibling prism_interviews_list, which lists rather than mints interviews.

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

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

The description implies the usage context (forward the invite to a guest who needs no account) and explains what focusPrompt does when supplied or omitted, but it never states when to choose this tool over near-neighbors like prism_series_create or prism_series_launch_wave, nor any exclusions or 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 cover the safety profile (readOnly, non-destructive, non-open-world). The description adds genuinely useful behavior beyond that: field availability is conditional – the memo appears once completed and the raw transcript only while no memo exists, and inviteUrl is only meaningful for interviews awaiting a guest. These conditional-return rules are not in the 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?

A single dense paragraph, front-loaded on what the resource is, with the conditional field rules trailing. Every clause carries information about returned content, though the sentence is long enough to require close reading.

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 carries the burden of describing return values and does so in detail, including the memo-vs-transcript conditionality. Missing only pagination/ordering and workspace scoping behavior, which are minor for a read 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 50% – workspace is documented in the schema, studyId is not. The description implies studyId scoping ('The study's...') but adds no format or constraint detail for either parameter. Baseline 3 is appropriate given the partial schema coverage.

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

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

The description clearly identifies the resource as a study's one-on-one interviews and enumerates the returned fields (guest, status, focus, memo, inviteUrl). The list verb is implied by the tool name rather than stated, and there's no explicit contrast with prism_interviews_create, but a reader grasps what it does immediately.

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

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

Usage is only implied: you call this to read a study's interviews. There is no statement of when to prefer it over prism_studies_get, prism_studies_results, or prism_interviews_create, and no prerequisites or exclusions are given. Adequate but with a clear guidance gap.

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

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

Annotations declare non-destructive, closed-world, non-read-only; the description adds real behavioral context beyond them — that generation consumes the workspace's inference credit and that the call may return `needs_confirmation` (matching the approvalId param). This is valuable disclosure, though the return format is not fully elaborated.

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 purpose and the axis mechanism, then cost and confirmation notes. Efficient with no obvious filler, though the opening all-caps framing is slightly rhetorical.

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

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

For a 7-param generative tool with no output schema, the description covers purpose, cost implication, and the confirmation flow, which are the key things an agent needs. It stops short of detailing return content, but that is largely minor here.

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 86%, so the schema already documents params (including count default, direction default, and workspace scoping rules). The description adds little param-level meaning beyond restating 'named semantic axis' and 'four directions', so baseline 3 applies.

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

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

States a specific verb (generate variations), resource (a Prism node), and mechanism (named semantic axis, four directions) with concrete axis examples. An agent can clearly distinguish this generation gesture 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?

Positions the tool as 'THE core Prism gesture' and gives axis examples, implying when to reach for it, but never states when NOT to use it or contrasts with alternatives such as prism_nodes_research. Usage is implied rather than delineated.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavior the annotations don't: 'thorough' runs three passes at ~3x credit, the call runs against the workspace's inference credit (a real cost signal), and it may return 'needs_confirmation'. That is meaningful extra context, though latency/citation-failure behavior is unaddressed.

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

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

Purpose is front-loaded, then cost/behavior details follow. The prose is dense but each sentence carries information (depth, focus, credits, confirmation). Slightly long but no clear 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 complex, credit-consuming, web-touching tool with no output schema, the description covers the essential stakes: what is produced, where it is stored, cost, and the needs_confirmation return. It stops short of explaining the required id parameters or the approval flow, but is largely complete for correct invocation.

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

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

With only 33% schema coverage the description must compensate, and it does explain the two most important optional params: what 'depth: thorough' entails and what 'focus' steers. However, required params fieldId and nodeId and the approvalId parameter receive no explanation, so the required inputs remain opaque.

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.' This clearly conveys what the tool produces and where it lands. It does not, however, name or differentiate itself from plausible siblings like prism_nodes_expand or prism_research_digest, so an agent still has to infer which research path to pick.

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 solid conditional guidance for parameter selection: pass 'focus' whenever the user has said what they want to know, otherwise a generic brief is answered, and use 'thorough' for broader coverage. But it offers no when-to-use/when-not guidance relative to sibling tools such as prism_nodes_expand, 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 declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered; the description adds one genuinely useful behavioral fact, that the call 'May return `needs_confirmation`', signaling an approval flow. It still does not explain what the destructive hint means here (e.g. whether pinning overwrites existing pins/colors) or how approvalId participates.

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; the core action leads and the caveat follows. It is efficient, though the middle sentence is a semantic aside rather than call-critical 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 6-parameter destructive mutation with no output schema and 33% schema coverage, the description is too thin: the approval/confirmation mechanism, workspace behavior, and what can be overwritten are all left to the schema and annotations to imply.

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%; pinned, nodeId, fieldId and approvalId carry no schema descriptions. The description only loosely gestures at 'pinned state and/or the color tag' and says nothing about approvalId's role in the needs_confirmation flow or fieldId's meaning, so it fails to compensate for the sparse schema.

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

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

States a specific verb ('Sets') plus the exact resources touched (pinned state, color tag), so the agent knows precisely what mutation occurs. It does not, however, differentiate itself from siblings such as entity_tags_set or prism_nodes_expand, leaving the agent to infer scope.

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 or when-not-to-use guidance is given. 'Pins are the cross-field shortlist' hints at the semantic role of pinning but never states alternatives (e.g. entity_tags_set for tagging) or prerequisites such as workspace resolution.

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

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

Annotations already declare the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description earns credit by disclosing the scope filter ('every study with responses') and the payload shape, including the non-obvious 'origin' taxonomy (standalone / canvas node / tracker wave) and the Ledger-kept insight field — details 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 sentences, front-loaded with the payload enumeration and closing with the routing advice. The field list is long but justified because there is no output schema; nothing is wasted, though the enumeration could be tightened slightly.

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 thoroughly. Remaining gaps are minor: no mention of ordering, pagination, or size/limit behavior for workspaces with many studies, and no note on behavior when a workspace has zero studies with responses.

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

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

There is one parameter and schema description coverage is 100%, so the schema already explains that workspace is required for personal tokens with no default and ignored for workspace API keys. The description adds nothing about this parameter, so the baseline 3 for a fully-documented single-param tool is appropriate.

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

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

The description names a specific artifact ('a cross-study digest') and enumerates exactly what it contains — every study with responses, title, origin, response count, latest analysis summary, top themes, and Ledger-kept insights. It routes distinctly away from siblings by pointing to prism_studies_get and prism_studies_results for follow-up, so an agent can tell it apart from prism_studies_list 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?

It states the triggering scenario ('The starting point for "what have we learned about X?"') and names two concrete follow-up alternatives with the object they act on. It stops short of saying when NOT to use it — notably it never distinguishes itself from the sibling research_findings_list or prism_studies_list_workspace, which a naive agent might otherwise reach for.

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 establish that this is a non-destructive write in a closed world; the description adds the consequential behavior beyond them: questions become immutable once the first wave fields (an irreversible commitment), scorer requires a paired metricId, and the call may return needs_confirmation (implying an approvalId retry loop). These are exactly the traits an agent must know before invoking.

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

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

Four dense sentences, front-loaded with what the tool does before the constraints. The em-dash asides carry real information rather than filler, though the prose is slightly chatty and could be tightened 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?

No output schema exists, and the description does disclose the one non-obvious return condition (needs_confirmation). Combined with the freeze semantics and schedule behavior, an agent has enough to call it correctly; only the scheduled-wave failure/backfill behavior is left 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 description coverage is already 92%, so the schema carries most parameter meaning. The description still adds cross-parameter semantics the schema cannot express — that a `scorer` needs a `metricId` to post readings — and frames `questions` as the frozen trendline instrument. It does not explain interval/dayOfWeek interaction beyond what the schema states.

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

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

States a specific verb and resource — creating a recurring research series that fields the SAME instrument on a schedule — and immediately scopes it with concrete examples (brand tracking, a weekly pulse) plus the key distinction that each wave is an ordinary study. An agent can tell this apart from the study-creation 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 clear selection context: waves launch on schedule automatically, or on demand via prism_series_launch_wave, which routes the agent to the right sibling. It also advises getting questions right with the user before the first wave because they freeze. No explicit when-not-to-use guidance, but the alternative path is 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 flag destructive/openWorld, but the description adds substantial context beyond them: it discloses that closing ends responses and posts to Ledger, that fielding spends credit for follow-ups/chats/analysis, that a live close is irreversible, and that it may return needs_confirmation. This is exactly the kind of behavioral disclosure that carries the burden annotations cannot.

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 most important fact ('CLOSES the current wave') with no preamble, and every clause carries operational weight. It is dense with em-dash subordination but nothing is filler; slightly heavy for a single paragraph.

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 appropriately surfaces the notable return (needs_confirmation) and covers destruction, credit cost, and irreversibility. The main gap is the absence of any guidance on the required seriesId and the approval/workspace parameters, which an agent must infer from the schema.

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

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

Schema description coverage is only 33% (only 'workspace' is documented; seriesId and approvalId are bare), and the description adds no parameter-level meaning for any of the three — no distinction between seriesId semantics, workspace selection, or how approvalId relates to the needs_confirmation flow. With low coverage, the description was needed to compensate 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?

States a specific dual verb+resource (closes the current wave, fields the next one from the frozen instrument) and gives the scope ('a series'). This clearly distinguishes it from siblings like prism_series_create and prism_series_update, which manage series metadata rather than advancing waves.

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

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

Gives an operational directive ('say both plainly before proposing') and notes manual launches don't move the schedule clock, which frames when to use it versus scheduler-driven launches. It does not explicitly name alternatives or state hard when-not conditions, so it stops 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds meaningful context beyond that: it explains what the returned records represent (recurring programs with cadence and score rules) and clarifies the domain boundary that waves are ordinary studies. It does not cover pagination, result volume, or whether series are workspace-scoped at all.

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 content is compressed into a single sentence with an enumerated field list, front-loading the resource definition. The ADR 0031 citation is arguably noise for an invoking agent, and the sentence runs long, but there is no padding or repetition.

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

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

With no output schema, the description usefully enumerates the returned fields, which is the main thing lacking elsewhere. However, for a list tool it omits pagination, ordering, and result-size behavior, and never states how many series are typically returned or what an empty result means.

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 there is only one optional parameter (workspace), whose semantics — default-workspace behavior and API-key handling — are fully documented in the schema. The description adds no further meaning about the parameter, so the baseline of 3 is appropriate.

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

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

The description identifies a specific resource — recurring research programs (series) — and enumerates the fields it surfaces (name, cadence, enabled state, next wave time, wave count, metric/score rule). Combined with the title 'List research series' and the sibling names prism_series_create/update/launch_wave, an agent can infer this is the read/list counterpart. It never states the verb 'list' in the description text itself and does not explicitly contrast with prism_series_get-style siblings, so it falls short of a 5.

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

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

There is no explicit statement of when to call this versus alternatives, and no prerequisites or exclusions. The closing note 'Waves themselves are ordinary studies' is an implied routing hint (use prism_studies_* for waves rather than this tool), but it is a disambiguation aside rather than usable when-to-use guidance.

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

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

Annotations already declare destructiveHint=true, so the bar is lower, yet the description adds real behavioral context: post-fielding instrument edits are refused with `invalid`, and the call may return `needs_confirmation` (implying the approvalId flow). It does not spell out what a successful mutation returns, but the refusal guard is disclosed.

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 then packs pause/resume, cadence, anytime settings, the instrument constraint, id provenance, and the confirmation hint into tightly worded clauses with no filler. The slash-and-backtick density is slightly hard to scan but 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 14-parameter mutation tool with no output schema, the description covers the mutability model, the hard refusal condition, the id source, and the confirmation envelope. The only meaningful omission is the unexplained metricId parameter, which is undocumented everywhere.

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?

At 50% schema coverage the description compensates by grouping parameters semantically: interval/scheduleTime/scheduleTimezone/dayOfWeek move the cadence, enabled toggles pause/resume, and name plus follow-up/auto-analyze settings change anytime. metricId remains unexplained in both schema and description, leaving one 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?

Opens with a specific verb and resource ("Edits a series") and enumerates exactly which fields are mutable, distinguishing scheduling fields from broadcast instrument fields. It does not name a sibling tool directly, though it hints at the create path via "the answer is a new series."

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 when/when-not rule: the instrument is editable only while no wave has fielded, and afterwards the correct move is a new series. It also points to prism_series_list as the id source. It stops short of explicitly contrasting with prism_series_create or launch_wave by name.

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

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

Goes well beyond the annotations by disclosing the incremental read scope, that prior themes are preserved, that the call returns immediately while work continues server-side, that it consumes inference credit, and that it may return needs_confirmation. These are exactly the behavioral traits an agent needs and none are derivable from readOnlyHint/destructiveHint alone.

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

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

Front-loaded with the core action, then layers the async/cost/edge-case details in a single dense paragraph where each sentence carries information. It is a touch dense but nothing is redundant.

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 right thing by describing the return shape (phase, upToDate, needs_confirmation) and the polling workflow. It is nearly complete for a mutation tool, but omits how to act on a needs_confirmation result and how approvalId relates to it.

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% (studyId and approvalId undocumented), so the description must carry more weight. It implicitly contrasts incremental mode with a full re-read, which maps onto reanalyzeAll, but it never names that parameter and says nothing about approvalId even though it warns about needs_confirmation. Adequate but leaves real gaps.

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

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

States a specific verb+resource ('kicks the theme analysis') and immediately scopes it as incremental with the prior themes carrying forward, which an agent can distinguish from a read tool like prism_studies_get. It also names prism_studies_get as the follow-up reader, so the purpose is unambiguous without opening either schema.

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

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

Gives clear operational context: run when you want fresh theme analysis, expect an async run, wait and re-read prism_studies_get, and treat upToDate:true as a healthy no-op rather than an error. It stops short of an explicit when-not-to-use or a comparison against the full clean-slate (reanalyzeAll) path, so it is strong context rather than 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?

Goes well beyond the readOnly/non-destructive annotations: it discloses the statistical tests (Welch t, two-proportion z), the 95% confidence level, the 30-response floor for testing, the exact vsRest output values (higher/lower/not_significant/not_tested), and an explicit caution never to present not_tested as 'no difference'.

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 operation and packs in only relevant details; the parentheticals and value enumerations earn their place, though the single dense paragraph is heavier than strictly necessary and could be split for readability.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating vsRest outcomes and their meaning. Combined with the statistical method and sample-size floor, an agent has everything needed to call and interpret this tool 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 80% and already documents each parameter, but the description adds real semantic value by explaining that the target question type determines the output (means + NPS on 0–10 for scale/number, per-option shares for choice/multi) and constraining the cut to acquisition source or a single-choice question.

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?

Names a specific operation (server-computed crosstab of a target question against a cut) and specifies both the target measurement types and the split dimensions, making it clearly distinguishable from siblings like prism_studies_analyze or prism_studies_segments.

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 to use this 'for every "does X differ by Y?" question instead of eyeballing raw rows,' giving clear positive guidance and a stated anti-pattern. It does not name a specific alternative sibling tool to use instead, so it falls just 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 destructiveHint=true, but the description goes further: it enumerates exactly what is destroyed, notes the operation is permanent, and discloses the needs_confirmation round-trip and required follow-up behavior. That is real behavioral context beyond the structured hints.

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 cascade, then the alternative, then the id source and confirmation protocol. Every clause 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 destructive tool with no output schema, the description supplies the cascade scope, reversibility, routing alternative, id provenance, and the needs_confirmation continuation path. An agent has everything required to call it safely.

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 studyId, workspace, and approvalId are already documented. The description still adds the provenance of the id (prism_studies_list_workspace) and the role of approvalId in the confirmation flow, which meaningfully complements the schema without re-teaching 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 (permanently deletes) and resource (study), plus the exact cascade scope: responses, interviews, analysis, share links. An agent immediately knows this is a destructive, full-cascade delete rather than a soft delete.

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 when to use it (a draft that won't be fielded, or a duplicate) and when not to, with the alternative sibling and parameter spelled out: 'prefer prism_studies_update closed: true — that keeps the data.' Nothing 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 establish it is a non-read-only, non-destructive, closed-world operation, and the description adds genuinely non-structured context: the output is a DRAFT not a live study, generation consumes inference credit (a cost side effect), and it may return `needs_confirmation`. These are useful behavioral disclosures beyond the annotations.

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

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

The core action and output type are front-loaded, and each sentence carries distinct information (what it generates, the review flow, the cost, the confirmation case). Slightly dense but no wasted sentences.

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

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

With no output schema and a simple 4-parameter mutation, the description covers the creation flow, cost, and confirmation behavior adequately. The main gap is that required params (nodeId, fieldId) and approvalId are left entirely to the schema.

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

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

Schema description coverage is only 25% — only `workspace` is documented. The description adds no meaning for `nodeId`, `fieldId`, or `approvalId`; notably, the mention of `needs_confirmation` is not linked to the `approvalId` parameter, which would have been the obvious place 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?

States a specific verb and resource ('Generates a short study... and creates it as a DRAFT') plus scope detail ('5-8 questions probing the node's problem space'). It is clear what the tool produces, but it never explicitly distinguishes itself from the sibling tools prism_studies_draft_from_interviews 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?

It describes the downstream workflow ('user reviews, previews, and opens it... or via prism_studies_update publish'), which routes the agent to a follow-up step. However, it gives no guidance on when to choose this tool over the other two draft variants, leaving that selection to inference from the name/title.

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

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

Adds substantial context beyond the annotations: it clarifies that the tool replaces the study's current questions but nothing fields until publish (softening the destructiveHint), discloses that generation consumes inference credit, and warns of a possible `needs_confirmation` response. These are exactly the behavioral traits 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?

A single dense paragraph that front-loads purpose, then mechanism, then prerequisites, then cost/return caveats. Every clause earns its place, though the em-dash appositives make it heavier than necessary.

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

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

For a mutation tool with no output schema, the description covers the replacement semantics, the credit cost, the precondition, and the confirmation state. The main remaining gap is the undocumented approvalId parameter, which an agent may need in the needs_confirmation 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?

With only 25% schema coverage across 4 parameters, the description must carry more of the load. It explains `steer` well with a worked example ('focus on pricing'), but says nothing about `approvalId` (only obliquely hinted by `needs_confirmation`) and nothing about `studyId` beyond implicitness.

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 ('drafts a survey') and immediately narrows it with 'GROUNDED in the study's completed interviews', which distinguishes it from the generic prism_studies_draft and prism_studies_draft_standalone siblings. The mechanism (recurring claims become questions, tensions become choices) tells an agent exactly what output to expect.

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 precondition ('needs at least one completed interview') and routes the agent to prism_interviews_list to check it. It does not explicitly contrast against prism_studies_draft or prism_studies_draft_standalone, so the when-to-prefer-this-over-siblings 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 it a non-destructive write, but the description adds meaningful traits beyond them: the artifact stays a DRAFT, it surfaces on the Studies page, generation consumes inference credit (a real cost signal), and it may return `needs_confirmation`. The confirmation flow is only hinted at, not explained, so it falls 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?

Purpose is front-loaded in the first clause, with supporting detail following efficiently. Slightly dense with em-dash asides and a parenthetical cross-reference, but every sentence carries information useful to an agent.

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 three parameters, the description shoulders more burden; it does well by explaining the created draft's lifecycle, cost, and the possible `needs_confirmation` response. The one gap is the unexplained `approvalId` parameter and no hint of the success response shape.

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, but `approvalId` is not, and the description never mentions any parameter by name. The 'May return needs_confirmation' line vaguely gestures at the approval flow that `approvalId` presumably serves, but the connection is never made explicit.

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 ('Generates and creates a DRAFT study') and its defining constraint ('isn't tied to any canvas node'), which cleanly separates it from the sibling prism_studies_draft and prism_studies_draft_from_interviews. Concrete examples (brand tracking, workspace-level research) reinforce the scope.

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 conditions for use — 'anything you can describe in a sentence' and explicitly not tied to a canvas node — which routes the agent away from the canvas-bound draft sibling. It stops short of naming the alternative to use when a canvas node IS involved, so it is strong context without explicit when-not/alternative 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 establish readOnly/non-destructive, and the description adds real beyond-schema context: the analysis is STORED (cached), activeRun signals a live analysis in progress requiring the caller to wait, and participantUrl only exists when the study is open and minted. These are non-obvious state conditions an agent must respect.

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 resource contents, and every clause is informative, but it crams several distinct ideas into one run-on sentence with nested parentheticals, making the activeRun and participantUrl conditions harder to scan than they need to be.

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 it well, naming the fields, the analysis state signal, and the share-link conditional. The one gap is that it never clarifies the tool's relationship to the sibling read/report tools.

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

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

Schema coverage is 50% and the description says nothing about either parameter — it describes return fields instead. studyId is self-evident and workspace is documented in the schema, so the burden is lightly handled, but no added meaning is provided for the parameters themselves.

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 exactly what 'get one study' returns (questions, response count, open/closed state, stored analysis), and the 'STORED analysis' phrasing implicitly separates it from prism_studies_analyze, which runs analysis. It never names a sibling for explicit contrast, so differentiation is inferential 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?

It gives genuine conditional guidance ('insights.activeRun set = wait for it before citing', 'cite theme strengths when reporting results'), but only about post-retrieval behavior. It never tells the agent when to call this versus prism_studies_list, prism_studies_results, or prism_studies_report.

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 externally. The description adds that this is a node-scoped read returning summary fields, but says nothing about ordering, pagination, or what an empty result means. Adequate given the annotation coverage, not rich.

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 fragment with no filler; the scope comes first and the returned fields second. It is appropriately sized for a simple list tool, though the fragment style leaves no room for the usage signal the tool needs.

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 usefully compensates by naming the returned fields. However, for a 3-parameter tool with two required, undocumented identifiers and no mention of pagination or result limits, the definition is only minimally complete.

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

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

Schema coverage is only 33%: only 'workspace' carries a description (default-workspace override rules), while nodeId and fieldId are bare strings. The description hints at nodeId via 'one Prism node' but never explains what fieldId is or why both are required, so it does not 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?

States a specific verb (list) and resource (feedback studies) and scopes it to 'one Prism node', which separates it in spirit from the workspace-wide sibling. It also enumerates the fields returned (title, question count, response count, open/closed), so the agent knows what it gets. It stops short of naming prism_studies_list_workspace as the alternative.

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

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

'Attached to one Prism node' implies the usage context (fetch studies for a specific node rather than workspace-wide), but there is no explicit when-to-use, when-not-to-use, or named alternative despite prism_studies_list_workspace and prism_studies_get existing as plausible siblings. Usage is inferable but not 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?

Annotations already declare readOnly=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds real behavioral context beyond that: sort order (newest first) and the full set of returned fields. It stops short of disclosing pagination or result-size limits, which for a workspace-wide list would be the remaining useful detail.

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 scope, then return fields, then routing to siblings — a logical ordering with no filler. The em-dash enumeration is dense but each item (origin types, sort order, returned fields) carries information; the only slight cost is that the field list makes the first sentence long.

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 enumerating the returned fields, and with only one fully documented parameter the schema burden is low. What remains unaddressed is list mechanics — pagination, caps, or how large a workspace list can get — which is a minor but real gap for a listing endpoint.

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

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

Schema coverage is 100% and the single workspace parameter is described thoroughly in the schema itself (token-type behavior, override semantics, API-key exemption). The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb (list) plus resource (studies) and explicitly enumerates the scope it covers — standalone, canvas-node, and series waves — which is precisely the boundary that separates it from the per-node sibling. It also names the returned attributes (title, question count, response count, state, parent field/node/series), so an agent knows exactly what it gets.

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?

Frames the tool around a concrete question ('which studies do we have?') and contrasts it with two named alternatives: prism_studies_list for the per-node view and prism_research_digest for the findings view, plus prism_studies_get for retrieval of a single study. Routing is explicit with no inference required.

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 genuinely useful context beyond the annotations: it consumes inference credit (a cost signal), may return `needs_confirmation`, is persisted on the study, and surfaces above the charts in the printable report. It stops short of warning what happens to a previously existing narrative, which matters given destructiveHint=true.

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

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

Two dense sentences that front-load the action and its inputs, then add operational facts. No filler, though the em-dash list of artifacts is on the edge of being a run-on.

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 has to carry more weight. It does explain where the result is stored and shown and flags the `needs_confirmation` return, but with a destructive write and a 33%-covered schema, the absence of any overwrite/approval detail leaves real 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 only 33%: studyId and approvalId are undocumented in the schema, and the description never mentions any parameter by name. The implicit sourcing 'from the study's computed record' hints at studyId, but workspace override and approvalId (plausibly tied to `needs_confirmation`) are left unexplained.

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 (writes the report's narrative layer) and resource (the study's report), with an enumeration of the outputs produced: executive summary, key findings with numbers, recommendations. It is clearly distinguishable from the many prism_studies_draft* siblings, though it never names an alternative to route against.

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 or when-not-to-use guidance, and no reference to the closely related siblings (prism_studies_draft, prism_studies_analyze, prism_studies_results) that an agent could confuse this with. The agent must infer the intended moment (post-analysis, on an existing study) entirely on its own.

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 closed-world, so the safety profile is covered. The description adds genuine behavioral value beyond that: it asserts the numbers are pre-computed and trustworthy ('without counting raw rows'), which is the key trait an agent needs in order to avoid redundant manual aggregation, and it discloses the quality-flag content (speeders, duplicate ids) that callers should expect.

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 directive sentence is well front-loaded and the closing 'ALWAYS...never...' instruction is the right note to end on. But the middle is a single sprawling sentence with three levels of nested parentheses enumerating every aggregate type, which is harder to scan than a short bulleted structure would be.

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 values, and it does so comprehensively — funnel stages, per-question aggregate types, and quality flags. Combined with annotations covering safety, an agent has everything needed to decide to call this tool and interpret the payload.

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%: the workspace parameter is documented in the schema, but studyId carries no description anywhere. The tool description says nothing at all about either parameter — no format for studyId, no guidance on when the workspace slug is required. With low coverage, the description was expected to compensate 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 names a concrete resource (a study's computed results) and enumerates exactly what those results contain — funnel metrics, per-question aggregates, quality flags — so an agent knows precisely what this tool returns. It does not, however, differentiate itself from near-neighbors such as prism_studies_analyze, prism_studies_cut, or prism_studies_report, which an agent could easily confuse it with.

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 directive — 'ALWAYS use this for quantitative questions about a study — never tally answers yourself' — which tells the agent both when to use it and what not to substitute for it. It stops short of naming the sibling tools (report, analyze, cut) that would cover other question types, leaving that inference to the caller.

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 safety is covered. The description still adds real behavioral value: it discloses the null return state and the shape of what is returned (segment mean vs overall), which is not in the schema.

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

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

A single dense sentence with the coverage constraint front-loaded and the null behavior plus alternative named at the end. No filler.

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

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

Although there is no output schema, the description compensates by describing the return structure and the null case, and it explains how segments come to exist. Complete enough for a read tool, with only the parameter gap remaining.

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%, and the description mentions neither studyId nor workspace. The undocumented studyId parameter gets no compensating explanation, so an agent gains nothing about parameters from the description beyond the schema's own workspace note.

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 (retrieves the stored k-means segmentation over a study's numeric answers) and details what the result contains (named segments, size, share, distinguishing features). It is clearly distinguishable from the compute sibling, which it explicitly names.

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 explains the null-when-not-computed condition and routes the agent to prism_studies_segments_compute with its prerequisites (30+ responses, 2+ numeric questions). What is missing is explicit guidance on when an agent should read segments at all versus other study outputs like results or report.

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 30+/2+ data thresholds, that recompute overwrites existing results, that naming runs against inference credit (a cost), and that a needs_confirmation result is possible. This is exactly the behavioral disclosure the destructiveHint implies, made concrete.

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 operation and followed by preconditions and side effects. Every clause carries information; none is redundant.

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 compute tool with no output schema, the description covers the operation, prerequisites, cost, destructive overwrite, and a possible confirmation outcome well. The remaining gap is parameter meaning, particularly approvalId, against only 33% schema coverage.

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

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

Schema description coverage is only 33% and the description adds no parameter meaning at all. The required studyId and the approvalId are undocumented in both places, leaving the agent to guess how approval relates to the mentioned needs_confirmation flow. A likely approvalId connection is never made explicit.

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 mechanism: 'Runs k-means over the study's numeric answers (silhouette-picked k) and names the discovered segments.' This clearly distinguishes the compute operation from generic study tools. It does not, however, explicitly differentiate itself from the closely named sibling prism_studies_segments, leaving the agent to infer the relationship.

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 concrete preconditions for use: 'Needs 30+ responses and 2+ numeric questions.' This is genuine when-to-use guidance that an agent can act on. It stops short of naming alternatives (e.g., prism_studies_segments or prism_studies_analyze) or stating when not to use it.

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 destructive/openWorld annotations by disclosing that publish is one-way (the participant link goes live), that questions replacement is whole and refused with `invalid` once responses exist, and that the call may return `needs_confirmation`. Null-clearing semantics for completionRedirectUrl and autoAnalyzeTarget are also spelled out, 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?

Front-loads the highest-stakes behavior (publish one-way, then closed) and every clause carries information. It is a single dense run-on rather than cleanly separated sentences, which slightly hurts scannability, but 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 12-param destructive mutation with no output schema, the description covers the consequential behaviors, error signaling (needs_confirmation, invalid), and id sourcing. It leaves approvalId unexplained and does not sketch the return payload, so it is strong but not exhaustive.

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 across 12 params, the description compensates heavily, explaining the meaning of title, questions (whole replacement), adaptiveFollowUps, endChatEnabled/endChatFocus, completionRedirectUrl, autoAnalyzeTarget, publish, closed, and where studyId comes from. It adds real semantics (null clears, one-way, lock behavior) rather than restating types.

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 specific verbs (publish, close, edit) and the exact resources touched (title, questions instrument, adaptiveFollowUps, closing chat, completionRedirectUrl, autoAnalyzeTarget). It also names siblings prism_studies_get (for reading the shape first) and prism_studies_list_workspace (for ids), so an agent can tell it apart from the read and list tools 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 conditional guidance: read prism_studies_get before replacing questions, and when the instrument is LOCKED the answer is a new study rather than this tool. That points to an alternative, but it never states the broad when-to-use vs prism_studies_delete or prism_studies_series_update, so it stops short of full coverage.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real value beyond that by disclosing the return content (study list with response/theme counts, desk-research presence) and a scope change note that interviews have moved to study level. It doesn't cover auth/limits, but for a read tool this is solid.

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 purpose is front-loaded in the first clause, followed by return contents and then routing guidance. The parenthetical asides are terse and each sentence carries distinct information (what it returns, the interview exception, when to reach for it). 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?

There is no output schema, so the description must convey returns — and it does, listing the study-level counts and desk-research flag. Combined with annotations covering the read-only profile, an agent has enough to call it correctly, though pagination or full result shape is not described.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning to the subjectType enum by clarifying it is 'today: a Prism node,' explaining why the enum has a single value and hinting at future expansion. It adds little for subjectId and workspace, but the schema already documents those.

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

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

The description names a specific verb+resource ('Cross-instrument findings for one subject') and enumerates exactly what is returned: attached feedback studies with response counts + theme counts, and desk-research existence. It also distinguishes itself from the sibling prism_interviews_list by stating interviews are now study-level. An agent can tell what this does and how it differs from neighbors 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?

Explicit when-to-use guidance is provided ('THE PLACE TO LOOK before proposing new research: cite what already exists') and a concrete alternative is named for the interview case ('read them per study with prism_interviews_list'). It lacks a general when-not clause, but the routing intent is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful non-annotation context: 'No authentication required — the docs corpus is public' and the shape of returned results (title, slug, public URL, snippet). It does not mention pagination or ordering, but it goes beyond 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?

The description is four short sentences, front-loaded with the core action, followed by return information, usage trigger, and auth note. Every sentence earns its place, and there is no repetition or 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 tool, the description covers purpose, return format, auth requirements, and usage triggers. It does not explain how this differs from search_workspace or list_docs/get_doc, and it lacks result-ordering or empty-result behavior, but it is otherwise sufficient for correct invocation.

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

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

Schema description coverage is 100%, and both parameters are documented in the schema itself. The description says the query returns a 'query-relevant snippet' but adds no syntax, format, or constraint details beyond what the schema already provides, so the baseline of 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 states a specific verb and resource: 'Search ZeroWidth product documentation.' It also names the return fields and the product scope with concrete examples (Compass, Workbench, Caliper, etc.), which lets an agent distinguish it from siblings like list_docs, get_doc, and search_workspace without opening schemas.

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

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

It gives clear usage context: 'Use this when the user asks about a ZeroWidth product ..., an API behavior, or a policy.' However, it does not name alternative tools (search_workspace, list_docs, get_doc) or state when not to use this tool, so it stops short of explicit 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 and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context beyond that: results are filtered to what the user can see and to kinds the token may read, and it discloses the hit shape (id, kind, workspace-relative path).

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, front-loaded sentences with no filler: purpose and coverage first, routing second, return/scope semantics last. Every clause carries information the agent can act on.

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 return-value burden and does so by describing the id/kind/path tuple and how the id feeds *_get tools. Combined with the permission scoping note, an agent has everything needed to call and use 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?

Schema coverage is 75%, so most parameters are already documented structurally. The description reinforces name/title matching but adds no new syntax or format detail for kinds, limit, or workspace, so the 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?

Opens with a specific verb (Finds) and resource (entities across every tool by name), then enumerates the concrete kinds covered (flows, pages, datasets, evals, rubrics, etc.). An agent can immediately distinguish this cross-tool search from the many per-tool list siblings.

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 when to use it ('Use it FIRST when the user names something without saying where it lives'), gives concrete examples ('the onboarding flow'), and names the alternative plus its selection condition ('reach for a tool's own list only when you already know the tool'). This is textbook when/when-not/alternative routing.

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