TheySaid

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and a closed-world scope, so the safety profile is fully covered by structured data. The description adds the segmenting dimensions and the metric set (counts, average completion progress), which is useful context for interpreting output. It does not state the default filtering of archived responses or anything about latency/auth, so it is a modest add.

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 that states the segmenting dimension first and the returned metrics second, with no filler or redundant restatement of the title. Nothing could be removed without losing 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?

The tool is simple (one required parameter), safety behavior is carried by annotations, and an output schema exists so return values need no prose explanation. The description covers the subject matter and metrics adequately; the only real gap is the absence of any usage routing against related breakdown/stats tools.

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

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

The description contributes nothing about either parameter. Schema coverage is 50%, but the undocumented parameter (projectId) is self-evident, while includeLowQuality carries a strong schema description with an explicit 'ONLY when...' conditional. Effective coverage is therefore high enough that the baseline of 3 is appropriate rather than demanding compensation in prose.

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

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

The description names the specific resource (a project's responses) and the exact breakdown dimension (collection channels), even enumerating the channel values and the metrics returned (counts, average completion progress). It is clearly distinguishable from siblings like question_breakdown or project_stats. It stops short of explicitly contrasting itself with those siblings, so it is clear but not fully differentiated.

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

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

There is no when-to-use or when-not-to-use guidance: nothing says to reach for channel_breakdown rather than question_breakdown, project_stats, or recent_responses. The only conditional behavior (default exclusion of low-quality responses) lives in the schema, not the description, so the description offers no routing help.

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 (readOnlyHint, idempotentHint, destructiveHint=false), and the description goes well beyond them: it enumerates the exact validation rules, the failure modes (missing, empty, oversized, non-HTML) and that they return an error, plus the meaning of needsConfirmation and the required user confirmation step via previewUrl.

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 validation purpose, then failure behavior, then next steps in a logical order with no filler sentences. It is dense and repeats the return field list that the output schema already declares, which costs a point on strict economy.

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

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

Given a one-parameter read-only validation tool with an output schema present, the description supplies everything an agent needs: purpose, validation contract, error handling, the needsConfirmation workflow, and the two possible follow-up calls. No behavioral 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 description coverage is 0%, so the single uploadId parameter is undocumented structurally. The description contextualizes it ('an uploaded design snapshot' and its reuse in propose_usability_test/relaunch_usability_test), which implies it is the upload identifier, but it never states where uploadId comes from or its format.

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 ('Verifies an uploaded design snapshot') and immediately narrows scope with the validation criteria (exists, non-empty, self-contained HTML, within size limit). This clearly separates it from siblings upload_design_snapshot and prepare_design_snapshot, which produce artifacts rather than validate them.

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 after success: propose_usability_test(uploadId) for a new test versus relaunch_usability_test(projectId, uploadId) for an existing project, and gives the recovery path on failure ('re-upload and check again'). It does not explicitly state the ordering relative to upload_design_snapshot/prepare_design_snapshot, so it falls just short of full when/when-not coverage.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds a genuine scoping constraint beyond that: 'No arguments — it is always the caller's organization,' ruling out querying other orgs.

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 returned fields, then usage, then the no-argument note. The enumeration of fields is informative rather than filler; nothing is wasted.

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

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

An output schema exists, so return values need not be re-explained. For a zero-argument read tool, the description covers what it returns, when to use it, and its scoping — nothing an agent needs 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?

Zero parameters, so the baseline is 4. The description correctly reinforces that the tool takes no arguments and is implicitly scoped to the caller's own organization.

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

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

States a specific resource (the caller's own company profile) and enumerates the contents: name, summary, category, products/services with features, benefits and USPs. No sibling tool returns company data, so an agent can distinguish it 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?

Explicitly says to use it to ground ideation and strategy, with concrete examples ('new project ideas', positioning, what to ask next). It gives clear positive context but names no alternatives or when-not conditions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds the prerequisite on id resolution but says nothing about how many 'recent responses' are returned, whether there is a cap or pagination, or what happens for an unknown contactId — meaningful gaps for a detail endpoint. With strong annotation coverage, this is adequate but 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?

Two sentences, no filler, and the identity of the resource is front-loaded before the returned field inventory. The parenthetical field list is long but each element carries information an agent would otherwise have to guess at.

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

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

For a single-parameter read tool with an output schema, the description is nearly sufficient: it says what entity is fetched and roughly what data comes back, and it explains how to get the id. The remaining omissions (recency window / response count, error behavior) are minor given that the output schema documents the return 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?

There is a single parameter at 100% schema description coverage, and the schema already says the id comes from contact_list. The description repeats that same guidance ('Resolve contact ids via contact_list') without adding format, validity, or failure semantics. Baseline 3 applies since 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?

The description names a specific resource (one contact/respondent) and enumerates exactly what is returned: name, email, phone, and recent responses across all projects with the insight/share id, project, summary, signal, and date. That is far more specific than the title 'Contact detail' and clearly separates it from the list-style sibling via the 'Resolve contact ids via contact_list' clause. It stops short of 5 only because the retrieval verb is implied rather than stated and the boundary with response_detail/recent_responses is not made explicit.

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

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

It gives a concrete prerequisite/context: resolve contact ids through contact_list first, which tells an agent how to obtain the required argument. It does not state when to prefer this over recent_responses or response_detail, so the alternatives dimension is missing.

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

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

Annotations already declare this a read-only, idempotent, non-destructive, closed-world read. The description adds value beyond that by enumerating the returned fields (name, email, total responses, last response date, projects) and the id-chaining workflow. It does not mention pagination limits or whether results are sorted, but the safety profile is fully covered by 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?

Three sentences, each doing distinct work: scope, return shape, then usage/routing. Front-loaded with the core action. Slightly dense with parenthetical ids, but nothing is wasted.

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

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

Output schema exists, so return values need no explanation, yet the description briefly summarizing them is a harmless aid. Combined with explicit sibling routing and param guidance, an agent has what it needs; only pagination/sort behavior is unstated, which is minor.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds semantic intent beyond the schema: `search` is framed as 'find a person by name/email' and `projectIds` as 'find who responded to given projects', clarifying the purpose rather than just the type. It does not restate the limit bounds, but the schema handles that.

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 (list the organization's contacts/respondents) plus the optional scoping dimension (responded to specific projects). This clearly distinguishes it from siblings like contact_detail (single contact) and responses_search (response-level lookup).

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

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

Explicitly names the two access paths: `projectIds` to find who responded to given projects, and `search` to find a person by name/email. It also routes the agent forward, telling it to pass a returned contact id to contact_detail or responses_search (contactId).

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/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely new behavior: auto-selection of comparable projects by theme similarity, and that results are headlines plus shared and divergent themes.

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, action first, then the two modes, then the return shape. Every sentence carries information an agent needs and there is no filler.

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

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

An output schema exists, so return values need not be detailed, and annotations carry the safety profile. The description covers both invocation paths and the general result content, leaving nothing material for an agent to guess.

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% (including maxProjects' default of 3), so baseline is 3. The description adds the '2+' minimum for explicit comparison, a constraint the schema does not state, plus a plain-language restatement of the null/one auto-find behavior.

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

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

Specific verb+resource ('Compare feedback across projects') that is easy to distinguish from generic listing tools. It clearly explains the two operating modes, though it never names the nearest sibling (similar_projects), which is the one an agent might 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?

Gives explicit invocation conditions: pass 2+ projectIds to compare those explicitly, or a single/none to trigger theme-similarity auto-discovery. That is clear when-to-use guidance, but it offers no exclusions or named alternatives, 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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds useful context by stating the flag helps tune models and by specifying which IDs to supply, but it does not describe reversibility, repeat-call behavior, or success effects, so the added value beyond annotations is moderate.

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 action and purpose, then the parameter sourcing. 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 three-parameter mutation with annotations and an output schema, the description covers the action, the source of required IDs, and the optional parameter. It is nearly complete, though it could say more about what a flag changes or whether it can be reversed.

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

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

Schema description coverage is 0%, so the description must carry the load. It identifies both required parameters and their source (testId and issue id from get_test_results) and notes that reason is optional, but it does not explain what reason should contain or how the IDs are formatted, leaving a real gap for an undocumented schema.

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

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

States a specific verb and resource: 'Flag a synthesized usability issue as inaccurate or hallucinated.' It also names a sibling, get_test_results, as the source for the IDs, so an agent can distinguish this tool from neighbors without opening the schema.

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

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

Gives a clear triggering condition: use when a usability issue is inaccurate or hallucinated, and explains that testId and issueId come from get_test_results. It does not name an alternative tool or an exclusion case, so it falls just short of a 5.

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

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

Annotations (readOnlyHint=false, idempotentHint=false) tell the agent this creates a resource and repeated calls are not idempotent; the description corroborates by stating it renders to a hosted image and returns a URL, i.e. a new artifact per call. It does not mention lifetime/stability of the hosted URL or any rate limits, leaving a small gap.

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

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

One compact sentence pair: purpose and return format first, then a dense semicolon-separated type glossary. Every clause carries either output-format or type-selection information; nothing is padded.

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

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

With an output schema present, the description need not explain return values, yet it usefully notes the URL/markdown embedding. It covers type choice and pie-series limitation, but is silent on constraints such as how many series the grouped/stacked types accept or label/value alignment requirements, which the schema only partially implies.

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%, so the baseline is 3, but the description earns an extra point by explaining the semantics of the enum beyond the raw value list (grouped vertical vs ranked lists vs part-to-whole) and by flagging that pie/doughnut consume only the first series. It adds no syntax guidance for title/labels/series or valueSuffix beyond the schema.

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

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

States a specific verb and resource ('Render a chart to a hosted image') and immediately specifies the output artifact ('returns a URL to embed in markdown as '). No sibling tool competes for this purpose, so an agent can route here unambiguously.

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 type list is effectively decision guidance: 'horizontal_bar (best for long category names or ranked lists)', 'pie / doughnut (share-of-total of ONE series)'. That tells the agent when each option fits. It does not cover when-not-to-use or call-level prerequisites, 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 establish readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds payload semantics (order is 1-based, total question count included, task-question follow-up flags) but says nothing about permissions, error behavior, or freshness beyond what annotations/schema 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-loaded with the core purpose before the field enumeration, and the id-resolution hint is placed last. The long dash-delimited field list is dense but each item is informative; slightly over-enumerated given an output schema exists.

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

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

Given a rich output schema and full annotation coverage, the description supplies everything needed to select and call the tool, including how to obtain the id. It over-explains return fields that the output schema already defines, which is redundant but not harmful.

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% for the single questionId parameter, so the schema already does the work. The description's cross-reference to 'project_overview's questions list' largely duplicates the schema's own '(from project_overview.questions)' note, adding only marginal value.

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 ('Full detail of ONE question') and enumerates the returned fields (type, text, 1-based order, total count, options, contentUrl, AI follow-up depth, follow-up enablement). The 'ONE' emphasis and field list distinguish it from the sibling aggregate tool question_breakdown.

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

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

Gives clear usage context ('inspect a question's current position, options, and settings') and a resolution prerequisite ('Resolve question ids via project_overview's questions list'). It stops short of naming an explicit alternative or when-not condition versus question_breakdown, but the operational guidance is solid.

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/idempotent/destructive annotations by disclosing that results are final only when phase is "done", and that partial/failed runs return partial findings plus a message. This is exactly the operational behavior an agent needs to avoid acting on incomplete data.

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, but much of the text enumerates return fields (resultsMarkdown, prioritizedIssues[], quickScan) that an output schema already documents, which the rubric treats as unnecessary. Dense and somewhat repetitive against the structured contract.

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

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

The behavioral gaps (phase finality, partial/failed semantics) are covered and return values are backed by an output schema. The only real omission is any guidance on the required testId, so it is complete 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?

The single parameter testId has 0% schema description coverage and the description never mentions it or how to obtain a value. With low coverage the description is expected to compensate and it does not, though the parameter is largely self-evident.

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

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

States a specific verb+resource ("Returns the usability results for a test") that cleanly separates it from get_test_status (status) and wait_for_results (blocking). An agent can identify the tool without opening the schema, and the sibling it is not is named.

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 names wait_for_results and the condition that distinguishes them ("returns the same data once a test finishes"), implying this fetches the current snapshot. It gives no explicit when-not/when-to instruction or prerequisite phrasing, so routing is clear but not fully spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: typical run duration ('several minutes') and the meaning of 'partial' and failureReason, which an agent needs to interpret a snapshot.

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

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

Two tight sentences with the core purpose front-loaded and the alternative named last. The field enumeration in the first sentence is dense but every clause carries information.

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

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

With an output schema present, the description needn't explain return values, yet it usefully summarizes them and adds timing plus an alternative tool. Nothing an agent needs to invoke it correctly is missing, though testId provenance is unstated.

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

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

Schema coverage is 0% and the single testId parameter has no description in either schema or description. The phrase 'for a running usability test' loosely implies testId identifies the test, but no format or source is given. Acceptable given the trivial single-param surface, but not enriched.

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 ('one-off progress snapshot for a running usability test') and enumerates the returned fields (phase, percent complete, failureReason). It clearly differentiates this lightweight snapshot from the sibling that follows a test to completion.

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

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

It explicitly routes the agent: 'wait_for_results is the usual way to follow a test to completion,' implying this tool is for quick point-in-time checks. It does not mention get_test_results, but the when-to-use-vs-alternative signal 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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: the empty-facet failure mode for unprocessed responses and the fact that data is scoped to a single session recording. It does not need to describe return format since an output schema exists.

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 resource definition, then the key, then the edge-case behavior, which is the right order. The facet catalogue in the first sentence is somewhat long and duplicates what the output schema already documents, but it is informative rather than 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 an output schema present, the description need not explain return shape, yet it still covers the lookup key source and the coverage limitation that would otherwise cause an agent to misread empty results as a bug. Nothing required for correct invocation 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?

Single parameter with 100% schema description coverage, so the schema already documents insightId. The description restates the same sourcing guidance ('from responses_search / recent_responses / response_detail') without adding syntax or format constraints beyond the schema.

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

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

Names the specific resource (video-derived UX signals from one usability-test recording) and enumerates the five facet families returned (findings, frictions, task performance, emotional moments, mental-model gaps) with enough detail to distinguish it from siblings. The lookup key (insightId) and its sources are stated, so an agent knows exactly what this returns and how to key it.

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

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

Gives a clear precondition: only usability-test responses whose recording was processed by video-metadata extraction have data, and other responses return empty facets — an explicit when-not signal. It also points to the sibling tools that supply the insightId (responses_search / recent_responses / response_detail). It stops short of naming an alternative tool for agents who want non-video response data.

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: it discloses the cost ('spends AI-tester runs'), the side effect ('creates a new project'), non-idempotency behavior in the specific form of alreadyLaunched: true on repeat calls, the failure mode PROPOSAL_NOT_FOUND for stale ids, and the expected runtime ('usually several minutes'). This is exactly the context an agent needs before a non-readOnly, non-idempotent launch.

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

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

Front-loads what the tool does, then the approval precondition, then the id-staleness rule, then edits, then outputs and alternatives. Sentences are dense but every one carries information an agent would otherwise have to guess; nothing is filler.

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

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

For a two-parameter but behaviorally consequential launch tool, it covers preconditions, cost, side effects, repeat-call behavior, error mode, return contents (testId, personas/plan, startedMessage with duration), and the follow-up tools for results and relaunches. An output schema exists and the description still names the key return fields, so nothing material is missing.

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

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

Schema description coverage is 0%, so the description must carry the load; it does well on the required param, stating that the latest proposalId is required and that a revise replaces earlier ids, with the precise PROPOSAL_NOT_FOUND failure. It also summarizes edits as 'add or remove tasks or questions, swap personas', but leaves several edit fields (audience/numTesters, voice settings, addLearningGoals, addQuestionSpecs, removeLearningGoalIndexes) unaddressed, so the coverage gap is only partly closed.

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

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

States a specific verb and resource: 'Starts the AI usability test for a proposal from propose_usability_test or revise_usability_test.' It immediately distinguishes itself from the planning siblings and from relaunch_usability_test, which is called out explicitly as the route for another batch on an existing project.

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 precondition ('only after the user has reviewed the plan and explicitly approved launching it'), names the producing siblings, names relaunch_usability_test as the alternative for an existing project, and points to wait_for_results for the results. When-to-use, when-not-to-use, and alternatives are all covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, and openWorldHint false, so safety is covered. The description adds practical behavioral context: cursor pagination, the pageInfo shape, and passing endCursor back as cursor for the next page. It does not add auth or rate-limit behavior, but those are not needed here.

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

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

The description is three tightly written sentences with no filler, and it front-loads the core action and scope before moving to usage and pagination mechanics. Every sentence contributes to selecting or invoking the tool correctly.

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

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

Given the rich annotations, 100% schema coverage, and an available output schema, the description is complete for an agent to call the tool correctly. It covers purpose, usage contexts, pagination mechanics, and return summary without redundantly re-documenting every schema field.

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 even without parameter detail in the description. The description mentions filtering, sorting, and pagination generally, and explains passing endCursor back as cursor, but that is already documented in the schema's cursor description. It adds little parameter meaning beyond the schema.

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

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

The description states a specific verb and resource: list the organization's projects with filtering, sorting, and cursor pagination. It also names use cases for discovery, disambiguation, and resolving a named project, which helps separate it from focused siblings like project_overview or project_stats. It does not, however, explicitly name a sibling alternative or contrast itself against one.

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

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

It gives clear when-to-use guidance: discover/disambiguate projects, resolve a project the user named, or page through a large set. That is useful context for an agent choosing among many project-related tools. It stops short of explicitly stating when not to use it or naming a sibling alternative.

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

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

Annotations already declare the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false). The description adds meaningful behavior beyond that: the mode switch between list vs. semantic search, the source kinds (files, links, pasted text), and that search returns a grounded answer plus snippets.

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 resource definition, then clarifies the two modes and the intended use. Sentences are purposeful, though the parenthetical source enumeration is slightly verbose.

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

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

An output schema exists, so return-value detail is not required. The description covers the dual-mode contract and intended usage well; only explicit alternative-tool routing 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 query param's dual meaning (question vs. null for listing) is already documented in the schema. The description restates this same semantic without adding format or syntax detail, 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 resource (the org's own uploaded 'Teach AI' knowledge sources) and its distinct dual behaviors: listing sources with no query, or semantically searching content with a query to return a grounded answer. This clearly separates it from siblings like search_ai_tester_voices or company_data, which operate on different corpora.

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 context for use ('to ground ideation or to answer questions from the org's own material'). However, it does not name alternative tools or state when NOT to use it, so an agent must infer routing against similar search siblings 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, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful behavior beyond that: it echoes the supplied message or returns 'pong', and it is instant, which is relevant for a health check.

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 purpose and immediately followed by output behavior and usage context. No sentence is wasted.

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

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

For a one-parameter, read-only health check with an output schema and full annotations, the description supplies everything an agent needs: purpose, return behavior, and when to call 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 description coverage is 0%, so the description must carry meaning for the optional message parameter. It does so by explaining that the tool returns the message you send, or 'pong' if none is supplied, clarifying the parameter’s effect and optionality.

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 utility: a health/echo check for the TheySaid MCP connection that returns the sent message or 'pong'. This clearly distinguishes it from every domain-oriented sibling such as list_projects or get_test_results.

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

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

It gives a clear context for use: confirm the server is reachable. It does not name alternatives or exclusions, but for a generic connectivity check that omission is minor.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=false), the description discloses that HTML is temporarily uploaded to TheySaid, that the snapshot expires, the exact return shape, and that this tool does NOT start a test. It also states the sequencing with check_design_snapshot and propose/relaunch tools.

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 routing decision and limitations are front-loaded and each sentence carries a constraint or next step. It is somewhat long for a no-parameter tool, but no sentence is pure filler.

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

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

An output schema exists, so return values need not be explained, yet the description still names { uploadId, uploadUrl, expiresInSeconds, nextStep } and lays out the full follow-up workflow. For an agent needing to call this correctly, nothing essential is missing.

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

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

The tool takes zero parameters, so the schema baseline is 4. The description still adds value by documenting the upload contract (text/html, inlined CSS/JS, absolute CDN URLs) even though that lives at the uploadUrl stage rather than in an input parameter.

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

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

The description opens with a specific verb+resource: 'Creates an upload slot for a self-contained design (HTML)'. It names the purpose (usability testing by TheySaid AI testers) and clearly distinguishes itself from siblings like upload_design_snapshot and propose_usability_test.

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

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

Gives explicit when-to-use (designs without a durable public URL, Claude Design/Artifact), when-not-to-use (expiring claudeusercontent.com links, live v0/Lovable/Bolt/Replit apps that lose styling in a snapshot), and alternatives (published public URL, upload_design_snapshot). 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 already cover safety (readOnly, idempotent, non-destructive, closed-world), but the description adds genuinely useful behavior: the estimate's derivation source and the accuracy caveat that branching rules may shorten the real path. It does not discuss caching, rate limits, or staleness of the estimate, which would have pushed it to 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?

One compact passage, front-loaded with what is returned, then the accuracy caveat, then the usage routing. Every sentence carries distinct information with no restatement of the title or schema.

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

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

An output schema exists and the description still names the key fields, so nothing about return shape is missing. For a one-parameter read-only lookup with annotations covering safety, the description is fully sufficient to call the 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?

A single required parameter with 100% schema description coverage; the schema already explains that projectId resolves via list_projects. The description adds no new parameter-level meaning, so the baseline 3 applies.

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

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

States the exact metric returned (`estimatedCompletionTimeSeconds` / `estimatedCompletionTimeMinutes`), its derivation basis (question types and AI follow-up depth), and its nature (a rough upper bound). It also distinguishes itself from the sibling `project_overview`, which carries the same figure, so the agent can tell the two 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 names the triggering condition ('when the user asks how long a survey/project takes') and names the alternative (`project_overview already includes the same figure`), effectively signalling when this call is redundant. That is as close to a when/when-not/alternative statement as a single-purpose read tool needs.

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, idempotent, non-destructive, closed-world), but the description adds real behavioral context beyond them: the severityCounts ordering (Mild < Moderate < Severe < Blocking) versus what `impact` means, how estimatedCompletionTime is derived, and the important conditional data-shape caveat that report runs omit themes/quotes/friction. That is materially more than the annotations supply.

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?

Nearly all content is substantive, but it is delivered as one enormous run-on sentence with nested parentheticals, so the most actionable routing hints (theme_detail, question_breakdown) and the report-run exclusion are buried mid-string rather than front-loaded. It is dense but not well structured for an agent parsing it quickly.

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 high-complexity aggregate tool with an output schema present, the description covers the important semantics an agent needs (friction vs impact, severity ordering, per-question drill-down paths, the report-run omission). It stops short of full completeness only because the includeLowQuality behavior and projectId resolution 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 coverage is 100% and both parameters are documented in the schema, including the explicit 'set true ONLY when the user asks' constraint on includeLowQuality, so the schema does the heavy lifting. The description adds no parameter-level meaning at all — it never mentions projectId resolution or the low-quality filter — leaving this at the baseline 3.

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

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

Names a specific resource (ONE project) and enumerates precisely what the payload contains: purpose, themes with sentiment/recommendations/response counts, friction with severityCounts and impact, ratings, keywords, quotes with share ids/URLs, questions, and estimatedCompletionTime. It also distinguishes itself from siblings by naming theme_detail, question_breakdown and get_question as drill-downs, so an agent can tell what this tool is and is not.

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 scopes the tool to a single project (implying cross_project_comparison for multi-project work) and routes the agent to the correct alternative for each follow-up need: themeId to theme_detail for quotes, question id to question_breakdown for distributions, or get_question for editable detail. It also gives an explicit when-not: in a report run themes, quotes and friction are absent, so list_observations should be used instead.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds that metrics are date-windowed and that low-quality/archived responses are excluded by default, but that exclusion is already stated in the includeLowQuality parameter description, and no further behavior (rate limits, auth, aggregation semantics) 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?

Three tight sentences: metric inventory first, usage trigger second, parameter note last. Front-loading is good and there is little waste, though the final sentence largely duplicates schema content and could be dropped.

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

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

With an output schema present, the description needn't explain return values, and it covers purpose, usage context, and the metric scope adequately. It is slightly short on sibling routing for an org that has many overlapping stat-related tools (stats_trend, channel_breakdown, cross_project_comparison).

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 four parameters are already documented in the schema, including the ISO date semantics of since/until and the low-quality exclusion. The description's 'Optional since/until ISO dates window the metrics' merely restates the schema and adds no new syntax or boundary meaning.

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

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

The description names a specific verb+resource ('quantitative metrics for ONE project') and enumerates the exact metric set returned (total responses, risk/growth signals, unread, avg conversation depth, first/last dates, per-channel breakdown). The emphasis on 'ONE project' cleanly separates it from cross_project_comparison, channel_breakdown, and stats_trend.

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

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

It gives a concrete triggering context — 'how is project X doing' / health questions — which is clear routing guidance. It does not explicitly name when to prefer siblings such as stats_trend (temporal trends) or channel_breakdown (channel-only views), so it stops short of full when-not/alternatives 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?

Beyond the annotations it discloses genuinely behavioral facts: nothing runs and nothing is spent, a draft is created, supplied fields are applied verbatim and echoed back, omitted fields get AI defaults, and progress notifications fire only when a progressToken is passed. It also states the failure behavior for missing or auth-walled prototypes. It loses a point for restating the return payload (proposalId, personas, tasks, questions) that the output schema already provides.

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

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

Dense but front-loaded: the no-op planning guarantee and the sibling routing come first, then plan composition, then return shape, then error paths. Long, but the length is mostly earned by the undocumented schema; the return-value recap is the one block that could be cut.

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

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

For a 12-parameter, zero-schema-description planning tool with an output schema and annotations, this is close to complete: it covers defaults, depth semantics, question shapes, audience precedence, preview-vs-launch boundaries and the missing-prototype failure mode. The gaps are a few secondary parameters (intent, project, prototypeImage) that an agent must guess at.

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 0% schema description coverage the description carries the load, and it delivers real meaning for the hard fields: the default is 2 tasks/3 questions, depth 'deep' means 5 tasks and 6 questions, question types and their option/scale shapes, and the audienceSpec-vs-audience-vs-personaIds precedence rule including the voiceIds source. It leaves intent, project, prototypeImage and the task successEnabled/feedbackEnabled flags undocumented.

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

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

Opens with a specific verb+resource+scope: 'Plans an AI usability test on a public prototype URL or an uploaded design (uploadId) without launching it'. It immediately distinguishes itself from relaunch_usability_test, revise_usability_test and launch_usability_test by name, so an agent can route correctly without opening the schema.

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

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

Explicitly names the alternatives and the conditions that select them: re-testing an existing project goes to relaunch_usability_test, edits go to revise_usability_test, and launching requires launch_usability_test after user approval. It also states the fallback when the prototype source is missing or login-gated (public URL or prepare_design_snapshot).

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/idempotent/non-destructive, so the safety profile is covered. The description adds a genuinely non-obvious semantic beyond that: for ranking questions the distribution counts first-place ranks only and the percentage is the top-rank share of respondents, preventing misinterpretation of the output.

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

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

Front-loaded with the core purpose, then the ranking caveat, then the id-resolution pointer. Dense but largely earning its place; the trailing fragment 'Optional since/until window the results' is awkward and adds little.

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

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

With an output schema present, return values need not be explained, yet the description still conveys output shape; combined with annotations and full schema coverage, an agent has enough to invoke it correctly. The missed includeLowQuality flag and lack of alternative-tool routing are the only minor omissions.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description only restates the since/until window ('Optional since/until window the results') and omits any mention of includeLowQuality, adding no meaning beyond the schema — baseline 3 is appropriate.

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

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

States a specific resource and scope: 'Deep results for ONE question' and enumerates exactly what it returns (response count, average, option distribution, top phrases). The 'ONE question' scoping plainly distinguishes it from multi-question and channel-oriented siblings like channel_breakdown.

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

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

It gives a concrete prerequisite for obtaining the required id ('Resolve question ids via project_overview's questions list'), which is useful. However, it never states when to prefer this over near-neighbors such as channel_breakdown, get_question, or response_detail, so selection guidance is only implied.

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

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

Annotations already establish the read-only, idempotent, non-destructive safety profile. Beyond that, the description adds useful behavior: results are the most recent responses, include specific summary/share fields, and support audience-group filtering including the 'not set' case.

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

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

The description is two front-loaded sentences with no filler. The parenthetical field list is slightly redundant given the output schema exists, but it remains readable and efficient.

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

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

For a four-parameter read-only tool with an output schema, the description covers intended use, filter behavior, and returned content sufficiently. It could be stronger by explicitly distinguishing this from responses_search, but no critical invocation details are 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 75%, with descriptions already provided for limit, includeUnset, and audienceGroupIds. The description reinforces the audience-group filtering interaction but adds little beyond the schema and does not clarify limit behavior or required projectId semantics.

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

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

The description clearly states the resource and scope: the most recent responses for a project, with named fields returned. It does not explicitly contrast itself with siblings such as responses_search or response_detail, so sibling differentiation is left implicit.

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

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

It gives explicit positive guidance: use for 'latest feedback' or to surface citable responses. It does not explain when not to use it or name alternatives like responses_search, but the intended context is clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, openWorldHint=true, so the mutation profile is covered. The description adds genuinely new behavior: it spends AI-tester runs (cost), reuses the testId (reusedProject: true), and echoes designRefreshed: true. Strong supplemental context, though a bit of it overlaps return-value territory.

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 re-run action, and each sentence carries real information. It is dense and long, with parenthetical synonyms and multiple workflow branches packed into one paragraph, which slightly hurts scannability.

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

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

An output schema exists, so return shapes needn't be explained, yet the description usefully previews the reusedProject/designRefreshed echoes. Combined with the mutation cost warning and workflow branches, an agent has everything needed to call it correctly.

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

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

Schema coverage is 0%, so the description carries the full burden and does: projectId is 'the testId from an earlier launch', numTesters is 'for this run', and uploadId triggers a specific workflow pointing the same project at a new design. All three params are fully disambiguated for a zero-coverage schema.

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

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

States a specific verb+resource ('Re-runs an existing usability-test project') and explicitly contrasts with siblings propose_usability_test + launch_usability_test, noting it does not create a duplicate project. An agent can distinguish this from the launch siblings without inspecting 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?

Explicit routing: use this to re-run on the same project, use revise_usability_test for audience changes, use prepare_design_snapshot/check_design_snapshot when passing a new uploadId. Covers when uploadId is needed vs when the hosted design is reused.

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/idempotent/non-destructive/closed-world, so the bar is lower; the description still adds real behavioral detail: friction moments are ordered worst-first with category, severity, observation and recording offset, missing audience groups render as 'not set', and report runs omit themes and per-question answers. The only gap is that it doesn't say what happens when an id resolves to nothing.

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

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

Front-loaded with the core purpose and the field inventory packed efficiently into one long sentence, followed by two short scoping sentences. The middle enumeration is dense and slightly run-on, but every clause carries information an agent would otherwise have to guess.

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-param read tool with an output schema, the description covers lookup keys, id provenance, edge-case rendering ('not set'), ordering of friction moments, and the report-run variation. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100% and both parameters already document their null-alternative semantics, so baseline 3 applies. The description adds the useful provenance of share ids, but does not clarify insightId sourcing or the failure mode when neither is supplied.

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: 'Full detail of ONE response', then enumerates exactly what that detail contains (transcript, answers, themes, friction moments, respondent, channel, signal, quality, shareUrl). The emphasis on 'ONE' plus the sibling list makes it clearly distinct from recent_responses and responses_search.

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

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

Explicitly states the two lookup keys and where share ids come from ('citations / responses_search / recent_responses'), which routes the agent to the right upstream tool. It does not explicitly say when to prefer recent_responses or responses_search over this tool, so it falls just short of full when/when-not 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 cover read-only, idempotent, non-destructive semantics, so the bar is lower, yet the description adds real behavioral context: a report run caps output at 10 responses, truncates each turn to 500 characters, and can attach full transcripts. It does not mention pagination or rate/permission constraints, which are the remaining gaps for a 14-parameter search.

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

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

Front-loads purpose and filter list, then return shape, then the export caveat — logical order with no filler. The single long paragraph and run-on parentheticals make the 10-response/500-character limit easy to miss, which costs a point.

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, optional-only search tool it covers the filter surface, output fields, the transcript opt-in, and the report-run truncation rule that would otherwise surprise an agent. Nothing an agent needs to call it correctly is missing, even disregarding the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds combination semantics the schema lacks — notably that frictionCategories and minFrictionSeverity can be used together ('a friction moment of that category / at least that severe') and that keyword matches summary plus respondent name/email. That goes modestly beyond restating the schema.

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

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

States a concrete verb and resource ('Search/filter individual responses') plus its scope (whole org or one project), and enumerates the filter axes. It is clearly distinguishable from sibling tools like recent_responses and response_detail because it is a multi-filter bulk search that returns a summary row per response.

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 trigger phrases ('negative responses about X', 'responses from <contact>', 'low-quality responses since <date>') and a clear conditional rule for includeConversation during exports. It never names a sibling alternative (e.g., recent_responses or response_detail) or states when-not to use it, so it falls short of full routing guidance.

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

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

The annotations declare destructiveHint=true and idempotentHint=false, but give no account of what is actually destroyed or replaced. The description fills that gap precisely: a revision returns an updated plan under a NEW proposalId that replaces the previous one, nothing is launched, and for launched tests the change is merely saved to the project and echoed back as `audience` until relaunch_usability_test. It also discloses a non-obvious side constraint — tester count can only change via `edits.audience.numTesters` — which is behavior no structured field conveys.

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

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

Dense and front-loaded, with the mode-selection rule first and the draft/launched split clearly sequenced; nearly every clause adds a constraint an agent could not infer. There is mild redundancy between "nothing is launched" and "nothing runs until relaunch_usability_test," and the single-paragraph block would scan faster as two mode-labeled segments.

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

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

For a four-parameter, high-branching mutation tool with no schema descriptions, the description supplies the decision rules, per-mode editability, side effects and hand-off to relaunch, and an output schema exists so return values need not be spelled out. The remaining gap is the un-described breadth of the nested `edits.audience` object, which the description gestures at rather than enumerates.

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 0% schema description coverage across four top-level parameters and a deeply nested `edits` object, the description carries the full burden and mostly delivers: it defines proposalId vs projectId, distinguishes free-text `changes` from structured `edits`, and explains index-based add/remove plus personaId swapping. It stops short on parts of the nested surface (e.g. `addQuestionSpecs`, `removeQuestionIndexes`/`removeLearningGoalIndexes` as distinct from the generic "remove ... by index", and the individual `edits.audience` fields), leaving some guessing for anything below `edits.audience.numTesters`.

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+resource ("Edits a usability test") and immediately splits the operation into two mutually exclusive modes keyed on `proposalId` (unlaunched draft) versus `projectId` (already-launched test). It also names the sibling that actually runs the test (relaunch_usability_test), so an agent can place this tool in the workflow without inspecting 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?

States the selection rule explicitly ("Takes exactly one of proposalId or projectId"), then gives per-mode capability boundaries: drafts can add/remove tasks, questions and learning goals by index and swap personaIds, while launched tests allow only audience changes. It goes further with a when-not rule — tasks/questions/goals of a launched test cannot be edited and a new test is needed instead — which is exactly the kind of exclusion that prevents wrong calls.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the return structure (voices array, hasMore, totalCount), pagination defaults (pageSize defaults to 30, max 100), and the critical distinction between voiceId and names. It does not mention rate limits or authentication, but adds substantial behavioral context.

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

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

The description is three sentences with no wasted wording. The purpose is front-loaded, followed by return details and usage context. The return shape is somewhat verbose given an output schema exists, but it remains helpful and well-structured.

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

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

Given the tool's complexity (read-only, open-world search), the description covers purpose, return format, pagination, and usage in related tools. Since an output schema exists, the explicit return structure is redundant but not harmful. All essential information for correct invocation is present.

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?

Despite 0% schema description coverage, the description explains that 'page' is 1-based and 'pageSize' defaults to 30 with a max of 100. The 'query' parameter is implicitly defined by the search criteria 'by name, style or accent', providing adequate semantic meaning for all three parameters.

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

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

The description states a specific verb ('Searches') and resource ('curated list of AI-tester voices') with search criteria (name, style, accent). It clearly distinguishes the tool from siblings, as none of the other tools perform this search.

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 explains that voiceId is the value used in propose_usability_test and revise_usability_test, and warns that voice names are not valid IDs. This provides clear context for when to use the tool, though it does not explicitly say when to avoid 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: the embedding basis, the fallback from objective to theme embeddings when objectives aren't embedded yet, the 0–1 score range, and the per-project `basis` field — all of which affect how results should be interpreted.

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 verb and mechanism, then modes, then the sibling routing. Dense but every clause carries information; slightly long, with mode details repeated in both schema and description.

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

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

With an output schema present, return-value details are unnecessary, and annotations cover the safety profile. The description supplies the mode selection rules, fallback semantics, and the sibling alternative, which is everything an agent needs to call it correctly.

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

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

Schema description coverage is 100% and already labels maxProjects as seed-mode-only and similarityThreshold as cluster-mode-only. The description restates the same mode coupling and the null-seed behavior without adding syntax, ranges, or edge cases beyond the schema, so the baseline 3 applies.

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

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

States a specific operation (find projects by semantic similarity) with the exact mechanism (objective/theme embeddings) and two distinct modes (seed ranking vs. full clustering). It explicitly names the sibling it is not — cross_project_comparison — so an agent can disambiguate 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 explicit when-to-use triggers ("which projects are like X?", "group my projects") and routes the contrasting case to cross_project_comparison with the condition that selects it. Nothing about tool selection 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 readOnly/idempotent/non-destructive, so the description only needs to add behavior beyond that. It does: it discloses the return shape (time buckets, per-signal split) and the intended pipeline into generate_chart, which helps an agent plan a multi-step call. It doesn't discuss default date range behavior when since/until are null, a minor gap.

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

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

Two tight clauses, zero filler: purpose first, then the usage/chaining instruction. Every phrase earns its place and the most decision-relevant information is front-loaded.

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

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

With an output schema present, the description needn't explain return values, and annotations cover the safety profile; the description supplies purpose, usage context, and chaining. The only omission is what a null since/until implies, a small but real gap for a time-series 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 80% and the schema itself documents since/until as ISO bounds, granularity's 'week' default, and the includeLowQuality exclusion rule — so the schema carries the semantic load. The description only echoes 'bucketed by day or week' (the granularity parameter) and adds nothing about projectId or the null date semantics, so baseline 3 is correct.

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

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

Names a specific verb+resource: 'Response volume over time for a project,' plus the dimensions of the output (bucketed by day/week, split by positive/negative/neutral signal). This clearly separates it from aggregate siblings like project_stats or question_breakdown, though it never names those alternatives explicitly.

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

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

Explicitly states when to reach for it ('trend / volume-over-time questions') and gives a concrete downstream step ('feed the points into generate_chart (line)'), which is genuinely actionable routing. It lacks an explicit 'do not use for X' exclusion against the other stats siblings, 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 readOnly/idempotent/non-destructive, so safety is covered; the description adds real behavioral detail on top: the since/until window filters both counts and quotes, a report run defaults to its own window and degrades the payload, and friction is null when the theme is not a negative project-wide observation. The severity ordering (Mild < Moderate < Severe < Blocking) clarifies a non-obvious data shape, though quote volume/limits and pagination are not addressed.

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 enumerates payload fields, with the id-resolution hint and report-run caveat placed at the end where they belong. It is dense—long parentheticals for severityCounts and impact—but essentially every clause adds information rather than restating the name.

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

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

An output schema exists, yet the description still explains the friction and quote structure and the report-run degradation, which is exactly the kind of deltas an agent needs. Remaining gaps are minor: no statement of quote volume limits or behavior when a theme has zero quotes/friction.

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 genuine meaning: since/until constrain both the response count and which quotes appear, and a report run substitutes its own window for the default. That is contextual behavior the schema's one-line ISO date notes do not convey.

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 ('Drill into ONE theme of a project') and enumerates exactly what comes back: summary, sentiment, recommendations, mention counts, friction with severityCounts/impact, and verbatim quotes with share ids/URLs. It also distinguishes itself from siblings by naming list_observations and project_overview as id resolvers rather than substitutes.

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 routing guidance: 'Resolve theme ids via list_observations or project_overview', and explains the report-run variant where the summary shrinks and recommendations are omitted because list_observations carries them. It does not explicitly state when to prefer project_overview over this tool in non-report contexts, so it stops just short of full when/when-not coverage.

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

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

Annotations cover the safety profile (destructiveHint=true, idempotentHint=true), and the description corroborates and enriches it: re-using an uploadId replaces the stored design (the destructive behavior, spelled out), the HTML is temporarily hosted at TheySaid (external data egress), and the return shape/next step is named. No contradictions with the 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?

Front-loaded with the fallback condition, then inputs, then return/next step. Dense but every sentence carries information (failure mode, temporary hosting, replacement semantics, non-actions). Slightly long, but no filler.

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

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

Despite an output schema existing, the description still names the returned fields and the required next call. Combined with the failure-mode trigger, replacement caveat, and explicit non-start of a test, an agent has everything needed to invoke this correctly and know what comes next.

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

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

Schema description coverage is 0%, so the description carries the burden. It clarifies that `html` must be the complete, self-contained design HTML and that `uploadId` determines where the design is hosted and that reuse replaces prior content. It does not specify the uploadId's format or origin beyond pointing at prepare_design_snapshot, which is the only real 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 (upload a design snapshot) and immediately frames it as the fallback path when the PUT to the `uploadUrl` from prepare_design_snapshot is blocked. This distinguishes it cleanly from sibling prepare_design_snapshot and from check_design_snapshot, which is named as the successor step.

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 ('fallback ... for when the PUT ... is blocked by the environment's network'), a concrete failure example ('Host not in allowlist'), the prerequisite tool that produces the inputs, the follow-up tool, and a negative exclusion ('This tool does not start a test'). 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 already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond them: server-side waiting with progress notifications, the stillRunning timeout contract, that re-invocation resumes waiting, and that partial/failed runs still return findings and design scans. This is exactly the operational context an agent needs.

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

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

Front-loads purpose and mechanism, then layers return shape and edge cases in a logical order. Dense but nearly every clause carries distinct information; slight density cost keeps it from a 5.

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

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

Covers the full lifecycle of a wait call: normal completion, timeout, re-invocation, and degraded (partial/failed) runs. Output schema exists so return values need not be detailed, yet the description still usefully names them without redundancy.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains maxWaitSeconds (optional, shortens a single wait) but says nothing about testId beyond the name. Partial compensation for a two-parameter tool where one param is self-evident.

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

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

States a specific verb (waits), resource (a usability test), and mechanism (server-side, bounded window) that cleanly distinguishes it from get_test_status and get_test_results. An agent can tell it apart from siblings without opening any schema.

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

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

Clearly frames the use case ('so no polling is needed') and explains the continuation pattern (calling again continues waiting) plus timeout behavior. It references get_test_results as the source of equivalent data but does not explicitly route between it, get_test_status, and this tool with a when-to-use/when-not rule.

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