TheySaid

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds what is actually computed (counts and average completion progress), which is mild extra value, but it omits any note about the default exclusion of low-quality responses or scoping to a single project.

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

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

A single, front-loaded sentence with no filler. It is a fragment rather than a full sentence, but every clause (channels list, counts, average completion progress) earns its place.

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

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

An output schema exists, so return values need no further explanation, and annotations cover safety. The description is sufficient for a simple two-parameter read-only aggregate; only the low-quality filtering caveat is left 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 50%: projectId is undocumented but self-explanatory, while includeLowQuality carries a thorough description in the schema. The description contributes nothing about either parameter, so it neither compensates for nor improves on 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 computation (how responses split across collection channels) and enumerates the channel values plus the reported metrics (counts, average completion progress). This clearly separates it from the sibling question_breakdown, though it does not name that sibling explicitly.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as question_breakdown or project_stats. The agent must infer the use case (channel-distribution analytics) entirely from the purpose statement.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the specific validation rules, the error conditions (missing/empty/oversized/non-HTML), and the meaning of needsConfirmation and previewUrl. Only the semantics of confirmation handling could be slightly richer.

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

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

The text is dense and front-loaded: purpose first, then return semantics, then error behavior, then next-step routing. The only mild redundancy is enumerating the return keys when an output schema already exists, though the explanation of needsConfirmation earns that space.

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 detail return fields, yet it still supplies the one non-obvious semantic (what needsConfirmation=true means) and the full follow-up workflow. Nothing an agent needs to call this correctly appears to be 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 single parameter has 0% schema description coverage and no enum, so the description should carry the meaning. It implies uploadId refers to a previously uploaded snapshot, but never states where the value comes from (presumably upload_design_snapshot) or its format. This is adequate given one trivial param but leaves a small gap.

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

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

The description uses a precise verb ('Verifies') on a specific resource ('an uploaded design snapshot') and states the exact validation criteria (exists, non-empty, self-contained HTML, within size limit). It is clearly distinguishable from siblings like upload_design_snapshot and prepare_design_snapshot.

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 downstream routing: after a successful check use propose_usability_test(uploadId) for a new test or relaunch_usability_test(projectId, uploadId) to re-test. It also names the failure path ('re-upload and check again'), so an agent knows exactly what to do in either branch.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the meaningful behavioral fact that it takes no arguments and always resolves to the caller's own organization, but discloses nothing about response freshness, permissions, or limits.

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

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

Two sentences, front-loaded with what is returned, then why it matters. The second sentence is somewhat long with nested parentheticals, but every clause carries usable guidance.

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 details are already covered and the description need not restate them. For a zero-parameter, annotated read-only tool, the definition supplies enough context for correct invocation, though it omits any note on how current the profile data is.

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 zero parameters, the baseline is 4, and the description reinforces this by explicitly stating 'No arguments — it is always the caller's organization', which pre-empts an agent hunting for an org or company ID. No further parameter meaning is needed.

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

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

The description names the resource precisely and enumerates its contents (company name, summary, category, products/services with features, benefits, USPs), so an agent knows exactly what it gets. It does not explicitly differentiate itself from a sibling like org_documents, which keeps it just below a 5.

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

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

It states when to use it — grounding ideation and strategy such as new project ideas, positioning, and what to ask next — with concrete examples. There is no explicit when-not guidance or named alternative, but the usage context is unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the notable fact that it exposes PII (email, phone) and aggregates responses 'across all projects', but says nothing about permissions, rate limits, or pagination for the response list.

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

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

Two tight sentences with zero filler; the resource and its returned fields are front-loaded, and the ID prerequisite follows immediately.

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 enumerate return values, and annotations carry the safety profile, so remaining needs are small. The one-parameter schema is fully documented, leaving only minor gaps around pagination of the 'recent responses' set.

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

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

Schema coverage is 100% and the single contactId parameter is fully documented in the schema, including its 'from contact_list' provenance. The description's 'Resolve contact ids via contact_list' repeats that schema note rather than adding syntax or format 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?

The description names a specific resource and scope: 'One contact (respondent)' with a concrete inventory of returned fields (name, email, phone, recent responses). The singular 'One contact' cleanly distinguishes it from the plural sibling contact_list.

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

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

It explicitly routes the agent to contact_list for ID resolution, establishing the prerequisite for calling this tool. However, it doesn't state when to prefer this detail view over the list view or other response-level siblings like response_detail.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds that contacts are respondents and enumerates returned fields, but it stays silent on pagination behavior and auth scope; with an output schema present, the field list is largely redundant.

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 that are front-loaded with purpose, then returns, then parameter routing; each earns its place. The returned-field enumeration mildly overlaps the output schema but remains readable.

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 full schema coverage, an output schema for return values, and annotations covering safety, the description supplies everything an agent needs: purpose, scope, parameter intent, and downstream id usage. No material gaps remain.

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 three parameters are already documented in the schema. The description's projectIds and search notes restate rather than extend the schema semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ("List the organization's contacts") plus the scope (optionally limited to project respondents), and equates contacts with respondents. This clearly separates it from contact_detail (single contact) and responses_search (response-level), so an agent can route 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 tells the agent when to use projectIds (find who responded to projects) versus search (find a person by name/email), and points the returned id downstream to contact_detail or responses_search(contactId). No explicit when-not-to-use or preference ordering against list-oriented siblings like recent_responses.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the automatic project-selection fallback when projectIds is absent or singular, and the shape of the comparison 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?

Three short sentences, zero filler, with the primary purpose front-loaded and the two usage modes following in order of importance. Every sentence earns its place.

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

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

With an output schema present, the description need not detail return values, yet it still summarizes them usefully. For a two-parameter, zero-required, read-only comparison tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a real threshold not stated in the schema: that explicit comparison requires at least two projectIds, while one or zero switches to auto-discovery. That is meaningful semantics beyond the parameter descriptions.

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 ('Compare feedback across projects') and elaborates with the two operating modes, so the agent knows exactly what the tool produces (headline plus shared/divergent themes). It does not, however, explicitly contrast itself with the sibling 'similar_projects', which is the closest potential confusion.

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 invocation conditions: 2+ projectIds for an explicit comparison, one or none to trigger auto-discovery of comparable projects. This is clear operational context, but it never states when to prefer this tool over alternatives such as similar_projects or project_overview.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the 'flag' wording is consistent with a non-read-only write. The description adds the downstream consequence ('to help tune the models'), but does not say whether the flag is reversible, how it affects the issue/result, or any auth requirements.

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 parameter guidance second. No redundant or filler text.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile. The definition is nearly complete, with only minor gaps around reversibility and the semantics of the reason 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?

With 0% schema description coverage the description must carry the param burden, and it does name all three (testId, issueId, reason), identifies where the IDs come from, and marks reason as optional. It stops short of describing the format or expected content of reason.

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 'flag' plus the resource 'a synthesized usability issue' and the semantic outcome ('inaccurate or hallucinated'). An agent can immediately tell this is a feedback/marking operation distinct from the get_test_results sibling that only reads data.

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 the source of the required IDs ('from get_test_results'), which routes the agent to call that tool first, and clarifies 'reason is optional'. It gives clear context but no explicit when-not-to-use or exclusion 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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, but the description usefully adds what the tool actually produces: a hosted image URL formatted for markdown embedding. That return-format disclosure is genuine value beyond the annotations.

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

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

Front-loaded with the core action and return value, then a compact type-to-purpose map. It is dense but every clause carries selection-relevant information; slightly list-heavy but no wasted sentences.

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

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

With an output schema present, the description needn't detail return shape, and it covers purpose, output URL, and type selection well. It leaves only ancillary questions (limits, styling) unanswered, which is reasonable for this 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%, but the description meaningfully enriches the most consequential parameter (type) far beyond the schema's terse 'Pick the type that best fits the data,' noting horizontal_bar for long category names and that pie/doughnut take a single series. It adds real meaning on top of 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') plus the concrete output ('returns a URL to embed in markdown as '). This clearly distinguishes it from every sibling, none of which produce charts or hosted images.

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 gives strong guidance for choosing among chart types, but that is really selection within the enum. It never states when to reach for this tool versus its siblings or any preconditions, so usage vs alternatives 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 declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavioral detail about the payload (1-based order, total count, task-question follow-up flags) but says nothing about permissions, rate limits, or error behavior.

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

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

Front-loaded with the resource and scope, then the returned fields, then usage. The field enumeration is long but every item is informative for selection; no filler sentences.

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

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

An output schema exists, so enumeration of return fields is partly redundant, yet the description still gives an agent enough to know it should call this tool to inspect a single question and how to source the id. Adequate for a simple single-param read tool.

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

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

Single required parameter with 100% schema coverage, so the schema does the heavy lifting. The description reinforces provenance ('from project_overview.questions'), which is genuinely helpful for resolving the id, though it adds no new format constraints.

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 (get) plus resource (question) with explicit scope 'ONE question', and it enumerates the returned fields (type, text, order, options, contentUrl, follow-up depth). This clearly distinguishes it from siblings like question_breakdown and project_overview.

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 when to use it ('inspect a question's current position, options, and settings') and how to obtain the id ('Resolve question ids via project_overview's `questions` list'). No explicit when-not or named alternative for the aggregate case, so not a full 5.

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

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

Annotations already cover the read-only, non-destructive safety profile. The description adds real behavioral value beyond that: it explains the phase lifecycle ('done' vs 'partial'/'failed') that determines whether data is final, and what a failed/partial run yields. This is substantive lifecycle context not present in the annotations.

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

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

Front-loaded with the core purpose, then lifecycle semantics, then the alternative. It is somewhat dense and spends notable text enumerating return fields (prioritizedIssues, quickScan, phase, message) that an existing output schema already captures, which is mild redundancy rather than waste.

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

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

Given a 1-param read-only tool with annotations and an output schema, the description is complete: it covers purpose, phase-gated finality, partial/failed behavior, and routes to wait_for_results. Nothing needed 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 0% for the single testId parameter, so the schema contributes nothing and the description must compensate. It only refers to 'a test' indirectly and gives no hint about the identifier's format or source (e.g., launch_usability_test). The required param remains semantically thin.

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

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

States a specific verb and resource ('Returns the usability results for a test') and clearly distinguishes itself from get_test_status by describing what results (issues, fix prompts) are returned. It names the sibling wait_for_results, so an 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?

Gives clear context: results are final only when phase is 'done', and partial/failed runs return partial findings. It names the alternative wait_for_results for waiting until completion. No explicit exclusions ('do not use when...'), but the selection conditions are well conveyed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context beyond that: the expected runtime ('runs normally take several minutes') and the meaning of the 'partial' failureReason, which is not derivable from structured fields.

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

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

Three tight sentences that front-load what the tool returns, then the runtime expectation, then the routing hint. Slightly dense with parenthetical caveats, 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?

An output schema exists, so the description is not obligated to explain return values, yet it still disambiguates the failureReason semantics and runtime. Combined with annotations covering the safety profile, an agent has enough to call this correctly.

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

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

Schema coverage is 0%, but there is only a single required parameter, testId, whose name and type make its meaning self-evident. The description does not restate the parameter or clarify its format, so it neither compensates for nor worsens the coverage gap – baseline 3 is appropriate.

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

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

States a specific verb and resource ('returns a one-off progress snapshot for a running usability test') and enumerates the payload fields (phase, percent complete, failureReason). It implicitly distinguishes itself from the sibling wait_for_results by being the one-off rather than the follow-to-completion tool.

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

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

Explicitly names the alternative and the condition selecting it: 'wait_for_results is the usual way to follow a test to completion,' which tells the agent this tool is for a single snapshot rather than polling. It stops short of stating when this tool is preferred or what to do if the test has already finished.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds a genuinely useful behavioral trait beyond annotations: non-processed responses return empty facets rather than erroring, which tells the agent how to interpret an apparently-successful but empty result. No auth or rate-limit context, but none is expected for a read-only lookup.

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, no filler, and the empty-facets caveat lands at the end where it functions as a guard. The first sentence is a dense facet enumeration that is slightly heavier than needed given an output schema exists, but each listed facet is substantive rather than padding.

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

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

For a single-parameter read tool with an output schema, annotations, and 100% schema coverage, the description supplies what the structured fields do not: the precondition for non-empty results and the provenance of the ID. Nothing needed to call it correctly is missing, though the facet enumeration partially duplicates 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?

There is a single parameter with 100% schema description coverage, and the description's mention of insightId sourcing largely mirrors the schema's own description. Baseline 3 applies since the schema carries the parameter documentation and the description adds no format or constraint detail beyond it.

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

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

The description names the exact resource and scope: video-derived UX signals for ONE usability-test session recording, and enumerates the five facet families returned. An agent can tell this apart from sibling retrieval tools because it is explicitly tied to video-metadata extraction rather than raw response data. It stops short of explicitly contrasting itself with response_detail or responses_search beyond naming them as ID sources.

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

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

It states the lookup key and where to get it (responses_search / recent_responses / response_detail), and gives a concrete precondition: only responses whose recording was processed by video-metadata extraction have this data, others return empty facets. That is a clear usage context. It does not spell out a 'use X instead when Y' branch for the ID-source siblings.

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

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

The description adds substantial behavior beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false): it spends AI-tester runs, creates a new project, and requires the latest proposalId with the concrete failure mode PROPOSAL_NOT_FOUND when stale. It also discloses the return shape (testId, final personas/plan, startedMessage with expected duration) and that results are retrieved via wait_for_results.

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

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

Front-loaded with the action and approval prerequisite, then prerequisites, failure mode, edits, return values, and the sibling alternative in a dense, well-ordered sequence. Every sentence carries distinct information with no filler.

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

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

For a launch/mutation tool with a rich nested edits schema, the description covers the full calling lifecycle: prerequisite tool, approval requirement, id freshness and failure mode, return values, results retrieval, and the correct alternative for re-runs. An output schema exists, yet the description still appropriately orients the agent on what comes back.

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 must carry parameter meaning, and it does explain proposalId semantics (latest id only, revise replaces earlier ids, stale id fails) plus the edits intent (add/remove tasks or questions, swap personas). It leaves the audience sub-object and addLearningGoals variants undetailed, so it doesn't fully compensate for the 0% coverage, but the high-value semantics are present.

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?

Starts with a specific verb and resource ('Starts the AI usability test for a proposal') and immediately roots the tool in its lifecycle by naming the producing siblings propose_usability_test and revise_usability_test. It also distinguishes itself from relaunch_usability_test for a different scenario, so an agent can disambiguate 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 states the when ('only after the user has reviewed the plan and explicitly approved') and the when-not rationale (spends AI-tester runs, creates a new project). It names the alternative relaunch_usability_test and the exact condition that selects it (running another batch on an existing project to avoid a duplicate).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the exact fields returned per project and the pagination contract (endCursor passed back as `cursor`), which the annotations cannot convey.

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

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

Front-loaded with purpose in the first clause, then usage, then return shape. Two sentences with essentially no filler, though the second sentence is dense with a list of returned fields.

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 spelled out, yet the description summarizes them anyway and explains pagination. With annotations covering safety and full schema coverage on parameters, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters including defaults and enum values. The description only reinforces the cursor parameter, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('List the organization's projects') plus the three capabilities the tool supports (filtering, sorting, cursor pagination), which distinguishes it from siblings like project_overview, project_stats, and similar_projects that operate on a single or related 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 explicit use cases: discover/disambiguate projects, resolve a project the user named, or page through a large set. This is clear when-to-use guidance, though it does not name an alternative tool or state when NOT to use this (e.g. when the project id is already known and project_overview is better).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, but the description adds substantive behavior beyond them: the dual-mode contract, the list fields returned (name, type, status), and that search returns a grounded answer plus supporting snippets. Missing only things like pagination or freshness limits, which are minor 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?

Three compact sentences, front-loaded with the resource definition followed by the two behavioral branches. The parenthetical gloss on 'Teach AI' documents earns its place by clarifying what counts as a source; nothing is padding.

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

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

With an output schema present, the description need not explain return values, and annotations carry the safety profile. Both operating modes and the intended use are covered, so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the schema description already explains that the query is searched semantically or null to list sources. The description restates that contract ('With no query, lists those sources. With a query, semantically searches their CONTENT') but adds no syntax or format guidance beyond the schema, so baseline 3 applies.

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

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

Specific verb+resource pair ('the organization's own uploaded knowledge sources') with the scope defined precisely (files, links, pasted text added by the org). It also disambiguates the two distinct modes — list vs. semantic search — so an agent can predict the behavior before 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 states when to reach for it: 'Use it to ground ideation or to answer questions from the org's own material.' That is clear context for selection, but no exclusion or named alternative is given, so an agent must infer the boundary against siblings like company_data on its own.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that: it is instant, it echoes the input back, and it defaults to 'pong' when no message is supplied.

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

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

Three short sentences, zero filler, with the core purpose stated first and the call-to-action last. Every clause earns its place.

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

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

An output schema exists, so return structure needn't be spelled out. For a trivial zero-required-parameter connectivity tool, the description covers purpose, behavior, return value, and latency — 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?

Schema coverage is 0% and the single 'message' parameter has no description in the schema, so the description must carry the load — and it does: it explains the parameter is echoed back verbatim and that omitting it yields 'pong', implying it is optional. It could be sharper about the nullable type, but the semantics are conveyed.

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 — a health/echo check for the TheySaid MCP connection — and describes its exact return ('the message you send (or "pong")'). No sibling tool performs this function, so the agent can identify 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 names the use case: 'use it to confirm the server is reachable.' That is a clear context for invocation. It stops short of stating when *not* to call it or naming an alternative, but no sibling tool overlaps with a connectivity check, so the gap 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?

Annotations declare a non-read-only, non-open-world, non-destructive write, and the description adds substantive context beyond them: the HTML is 'temporarily uploaded to TheySaid', the response shape {uploadId, uploadUrl, expiresInSeconds, nextStep}, the required content form (text/html, inlined CSS/JS, absolute CDN URLs), and the explicit disclaimer that it does not start a test.

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 purpose, then sequencing via 'Then:' and 'This tool does not start a test'. It is long and includes mild redundancy — the point that live apps need a public URL is made twice — but nearly every sentence carries actionable information given the tool's complexity.

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

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

Given an output schema exists, the return-value explanation is a bonus rather than a necessity, and the definition still covers the full workflow (upload, check, propose/relaunch), the fallback tool, and the static-vs-live boundary. Nothing an agent needs to invoke it correctly is missing.

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

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

With zero parameters, the baseline is 4. The description usefully documents the upload contract that the agent must fulfill (single PUT to uploadUrl, content types, inlining rules), even though this concerns the workflow rather than named parameters.

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

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

States a specific verb and resource — 'Creates an upload slot for a self-contained design (HTML)' — and immediately scopes the purpose to enabling a usability test. It also distinguishes itself from the similarly named sibling upload_design_snapshot by positioning that tool as the fallback when the upload host is blocked.

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 ('designs without a durable public URL, such as a Claude Design or Artifact') and when-not ('live apps built with v0, Lovable, Bolt or Replit are better tested through their published public URL'; temporary preview links expire). It names the follow-on alternatives propose_usability_test and relaunch_usability_test, and clarifies it does not itself start a test.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed world). The description adds real behavioral context beyond that: it is a 'rough upper bound' because 'branching rules may shorten the actual path', and the figure is 'derived from question types and AI follow-up depth'. That caveat meaningfully informs how much to trust the value.

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

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

Three tight sentences, front-loaded with what it returns and immediately followed by the caveat and the usage/routing hint. Every sentence earns its place with no padding.

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

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

An output schema exists, so return values need no explanation, yet the description still clarifies the derived nature and limitation of the value. For a simple read-only single-param tool it is fully complete.

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

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

Only one parameter (projectId) with 100% schema description coverage, so the schema carries the semantics. The description adds nothing about the parameter itself; baseline 3 is appropriate.

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

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

States a specific verb+resource ('How long ONE project takes a respondent to complete') and names the exact return fields (estimatedCompletionTimeSeconds/Minutes). Capitalizing 'ONE' clearly scopes it to a single project, and naming project_overview as carrying the same figure distinguishes it from siblings.

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

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

Explicitly says when to use it ('when the user asks how long a survey/project takes') and points to project_overview as containing the same figure. It stops short of saying the agent should prefer project_overview instead, so routing is implied rather than fully directive.

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 a safe read (readOnlyHint=true, destructiveHint=false), lowering the bar. The description still adds useful context: quotes carry share ids for citation, estimatedCompletionTime is a rough upper-bound, and it exposes the fields returned. The archived-response default is only covered in the schema, not 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?

It is front-loaded with the core purpose and every clause maps to actual output content, so little is wasted. It is, however, a single dense run-on with nested parentheticals that is heavier than needed.

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 formatting, and it already covers scope, contents, and onward routing. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so both params (projectId, includeLowQuality) are fully documented in the schema. The description adds no parameter-specific meaning beyond that, so the baseline of 3 applies.

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

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

The description states a specific verb+resource ('Deep overview of ONE project') and then enumerates the exact contents: themes with sentiment/recommendations/response counts, average ratings, keywords, quotes with share ids, questions, and estimatedCompletionTime. The 'ONE project' framing cleanly separates it from cross_project_comparison and sibling list tools.

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

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

It explicitly routes the agent onward: use question_breakdown for a full per-question distribution, or get_question for editable detail. That is clear alternative guidance, though it does not state when to prefer this over the likely lighter-weight sibling project_stats.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the metric inventory and date-windowing scope, but nothing about pagination, latency, or freshness beyond that.

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

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

Front-loaded with the metric list, then usage, then the optional date params — a sensible order. The enumeration of return fields partly duplicates the output schema, a mild redundancy, but 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?

An output schema exists, so return values needn't be spelled out, yet the description does so anyway and covers the single-project scope, usage, and date windowing. For a read-only 4-param tool, nothing material an agent needs to call it is missing.

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

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

Schema coverage is 100% and each parameter already has a descriptive entry, including the low-quality exclusion rule and the projectId resolution hint. The description only restates that since/until window the metrics, adding no format or edge-case detail beyond the schema. 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?

The description names a specific resource (one project) and enumerates a concrete metric set: total responses, risk/growth signals, unread responses, avg conversation depth, first/last dates, and per-channel breakdown. The 'ONE project' emphasis distinguishes it cleanly from cross_project_comparison 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 clear use case — 'how is project X doing' / health questions — and implicitly scopes to a single project. However, it never names or excludes close siblings like project_overview or stats_trend, so an agent still has to infer which one to pick for overlapping 'health' questions.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description reinforces this with consequential detail the annotations cannot carry: no AI testers run, nothing is spent, a draft is created, set fields are applied verbatim and echoed, omitted fields get AI defaults. It stops short of stating auth/permission requirements or rate limits, but the mutation-safety picture is well covered.

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

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

Front-loaded with the core action and the 'nothing is spent' constraint before routing details. It is a dense single block, but for a 12-parameter planning tool most sentences earn their place; the routing and precedence rules are load-bearing 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?

Given 12 optional params, a write annotation set, and an existing output schema, the description supplies the decision-relevant context an agent needs: source requirements, draft-vs-launch semantics, defaults behavior, and field precedence. Return values needn't be documented because an output schema exists, though the description still lists them helpfully.

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 12 params, the description carries the full burden and delivers real semantics: learningGoals/audienceSpec/tasks mapping, the audienceSpec-vs-audience-vs-personaIds precedence rule, depth quick/deep, default plan sizing, and that voice.voiceIds expects ElevenLabs IDs from search_ai_tester_voices. It does not explain intent, prototypeImage, or the project sub-fields, so coverage is strong but not exhaustive.

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 and scope: 'Plans an AI usability test on a public prototype URL or an uploaded design (uploadId) without launching it'. It explicitly distinguishes itself from the sibling verbs it could be confused with (relaunch_usability_test, revise_usability_test, launch_usability_test), so the agent can separate them 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?

Gives explicit when/when-not routing: re-testing an existing project goes to relaunch_usability_test, edits go through revise_usability_test, and the test starts only via launch_usability_test after approval. It also names the precondition (public URL, or a snapshot via prepare_design_snapshot) and the failure path (login-gated URL, no source).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful semantics not in the annotations: that ranking distributions count FIRST-place ranks only and that each respondent contributes one entry, so percentages read as share of respondents. It doesn't discuss pagination or result-size limits.

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

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

Front-loads the return contents in one dense sentence and reserves the second for the ranking caveat, which is the highest-value clarification. The trailing fragment 'Optional since/until window the results' is grammatically incomplete and slightly wasteful, keeping 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?

With read-only annotations covering safety, a fully documented schema, and an output schema present, the description fills its remaining job well: it clarifies the non-obvious ranking-percentage semantics and points to where question ids come from. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents since, until, projectId, questionId, and includeLowQuality in detail. The description only restates the date window as 'optional since/until window the results' and adds no format or semantic detail beyond the schema, matching the baseline for full-coverage schemas.

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 (results for ONE question) and enumerates exactly what it returns: response count, average, option distribution, and top phrases. It also distinguishes itself from siblings like get_question and channel_breakdown by scoping to a single question's aggregated 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 context: resolve question ids via project_overview's `questions` list, and states the optional since/until window. It does not explicitly name when to prefer a sibling (e.g. channel_breakdown or get_question), so the when-not guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered structurally. The description adds only the returned field list and a use case; with an output schema present, that field list largely restates structured data rather than adding new behavior context such as result counts or limits.

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

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

Two short clauses; the resource and field list are front-loaded and the usage trigger follows. No filler, though the parenthetical field enumeration is somewhat dense and partly redundant with the output 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?

For a simple read-only list tool with an output schema covering return shape and annotations covering safety, the description is adequate: it says what comes back, how many by default (via schema) and the typical intent. Only the missing projectId provenance keeps it from being fully self-contained.

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

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

At 50% schema coverage, projectId is undocumented in both the schema and the description — no hint about where the id comes from (list_projects). The description adds nothing about the limit parameter either, so it fails to compensate for the coverage gap.

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

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

States a specific resource and scope: the most recent responses for a project, plus the fields carried (summary title, sentiment, quality, channel, share id, date). That distinguishes it from response_detail (single response) and responses_search (filtered search), though it never names those siblings explicitly.

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

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

Gives usable trigger phrases ('latest feedback', 'surface citable responses'), which implies when to reach for it. It stops short of explicit when-not guidance or naming responses_search / response_detail as the alternatives, leaving the agent to infer the boundary.

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

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

Despite annotations already covering the safety profile (readOnly=false, destructive=true, openWorld=true), the description adds substantial context: it spends AI-tester runs, does not change audience or questions, does not create a duplicate project, echoes designRefreshed: true, and returns the reused testId. This is behavior beyond what annotations 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?

The core purpose is front-loaded and nearly every sentence carries distinct information (cost, project reuse, uploadId behavior, audience caution, return values). It is dense and fairly long for a single paragraph, but there is little redundancy.

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

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

For a mutation tool with three params and an output schema, the description covers the essentials: what it mutates (spends tester runs), what it does not change, how to redirect it, and where results come from. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: projectId is defined as 'the testId from an earlier launch,' numTesters as optional testers for this run, and uploadId as an optional pointer to a newly prepared design snapshot with the resulting designRefreshed: true behavior explained.

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

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

States a specific verb+resource: 'Re-runs an existing usability-test project.' It explicitly names the siblings it differs from (propose_usability_test + launch_usability_test) and clarifies it reuses rather than duplicates the project, so an agent can distinguish it without opening any schema.

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

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

Gives explicit when-to-use and alternatives: use this to re-run on the same project, versus launch_usability_test to create a new one. It also routes related needs to revise_usability_test (audience changes) and prepare_design_snapshot/check_design_snapshot (updated design), and notes results come from wait_for_results or get_test_results.

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

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

Annotations already declare the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's remaining job is narrower. It does disclose the identity of the respondent (name/email) and the breadth of data returned, which is useful privacy-relevant context, but says nothing about permissions or cost.

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 front-loaded sentence that leads with the essential scope then enumerates fields; no wasted preamble. It 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 structure, and it covers lookup keys, their sources, and the field categories returned. It stops short of covering edge cases such as what happens if neither id is supplied, but that 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 coverage is 100% and both params are documented there, so the baseline is 3. However the description adds real value by explaining the provenance of shareId (citations / responses_search / recent_responses), which the schema does 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 scope ('Full detail of ONE response') and enumerates exactly what comes back: transcript with messageId/questionId, per-question answers, themes, respondent, channel, signal, quality, date. The 'ONE' framing immediately distinguishes it from list-style siblings like 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?

Gives clear lookup keys (insightId or shareId) and, importantly, tells the agent where share ids originate: citations, responses_search, recent_responses. That is functional routing guidance, though it never states an explicit when-not-to-use condition vs. those siblings.

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

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

Annotations already declare readOnlyHint/openWorldHint=false/destructiveHint=false, so the safety profile is covered; the description adds non-obvious behavior such as low-quality responses being archived and excluded from all other filter combinations unless requested, and the cost/implication of includeConversation (bulk-fetched transcripts). It stops short of stating rate limits or truncation behavior when limit caps at 50.

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 purpose, then filters, then return shape, then the includeConversation caveat, then examples — a sensible ordering. It is dense and long-ish for one paragraph, but every clause carries information; no filler sentences.

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

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

An output schema exists so return values are supplementary, yet the description still summarizes them usefully; annotations cover safety, and the description covers the tricky parts an agent could get wrong (archived low-quality exclusion, when to request conversations). Nothing material is missing for a 10-param optional-filter read tool.

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

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

With 100% schema coverage the baseline is 3; the description goes further by explaining cross-field semantics the schema states only per-parameter: keyword matches summary + respondent name/email, contactId comes from contact_list, projectId null means whole org. It aggregates the filter model rather than repeating individual descriptions.

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 with scope ('Search/filter individual responses across the whole org or one project') and enumerates the filter dimensions and return fields. It implicitly separates itself from recent_responses (unfiltered recency list) and response_detail (single transcript) by describing bulk filtered search, so an agent can route correctly.

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 trigger phrasings ('negative responses about X', 'responses from <contact>', 'low-quality responses since <date>') and a clear conditional for includeConversation ('use this when EXPORTING'). It does not explicitly name when NOT to use it or point to recent_responses as the unfiltered alternative for the same task.

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 that the updated plan replaces the previous one under a new proposalId, that nothing is launched until relaunch, that numTesters only changes via edits.audience.numTesters, and that launched-test edits are saved and echoed back as audience. This matches destructiveHint=true with concrete detail on what is replaced.

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 branches cleanly into Draft vs Launched, so the branching is scannable. It is dense and a bit long, but nearly every clause encodes a constraint that would otherwise be missed.

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

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

For a 4-param, deeply nested mutation tool with an output schema, the description supplies the operational rules an agent needs (which id, which edits allowed, launch state, replacement semantics). The only gap is the internal structure of edits.audience, which is neither in the schema descriptions nor the text.

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 coverage the description must carry the load, and it explains all four top-level params (proposalId, projectId, changes, edits) plus the meaning of key edit sub-operations (add/remove tasks, questions, goals by index, swap personaIds). It does not, however, explain the many nested audience fields (voice, personality, age ranges), leaving that part of the deep schema unannotated.

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

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

States a specific verb (Edits) and resource (usability test) and immediately splits the operation into two precise modes keyed by proposalId vs projectId. An agent can distinguish this from propose_usability_test and relaunch_usability_test without opening any schema.

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

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

Explicitly states when to use proposalId (unlaunched draft) vs projectId (already-launched test), names relaunch_usability_test as the follow-up and notes tasks/questions/goals of a launched test cannot be edited and 'a new test is needed for that.' When-to-use, when-not-to, and the alternative are all present.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the return shape, 1-based paging, and default/max page size, which an agent needs to page correctly.

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 purpose, then return shape, id semantics, and pagination rules in sequence with no filler. It is dense and slightly packed, but every clause adds actionable information.

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

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

For a three-parameter search tool it covers purpose, id semantics, downstream consumers, and pagination. The return-shape sentence is technically redundant against the output schema but harmless, and nothing an agent needs to call or page 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 0%, so the description must carry the load. It does: query is characterized as matching by name, style or accent, page is stated as 1-based, and pageSize is given a default of 30 and a max of 100. Only the exact query syntax (substring vs fuzzy) is left unspecified.

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 (Searches) and resource (curated list of AI-tester voices) plus the search dimensions (name, style, accent). It also ties itself to the sibling tools that consume its output, so an agent can place it precisely in the workflow.

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 explains the downstream purpose: the returned voiceId feeds audienceSpec.voice.voiceIds in propose_usability_test and edits.audience.voice.voiceIds in revise_usability_test, and warns that voice names are not valid ids. It does not state explicit exclusions or when NOT to call it, 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 it as a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), yet the description adds real behavioral detail beyond them: the objectives→themes fallback, the per-project `basis` marker, and the 0–1 score range. It does not discuss cost/latency of the all-projects clustering mode, so it falls short of a 5.

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

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

Front-loaded with the core purpose, and every sentence carries a distinct fact (fallback, seed mode, cluster mode, basis field, sibling routing). It is dense—the second sentence packs several clauses—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?

An output schema exists, so return formatting need not be explained, and the description still covers both operating modes, the fallback logic, and the routing decision to a sibling. Nothing needed 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%, so all three parameters are already documented including their mode restrictions and defaults. The description restates the seed/null distinction and the basis/score semantics rather than adding new syntax or constraints, which is the baseline-3 case.

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 (find/rank/cluster) and resource (projects) plus the mechanism (objective embeddings with theme-embedding fallback). It explicitly distinguishes itself from cross_project_comparison, so an agent can route between them 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 dual-mode usage: pass a seedProjectId to rank similar projects, pass null to cluster the whole org, and names the alternative (cross_project_comparison) with the condition that selects it (compare a known set side-by-side by theme). Two concrete user phrasings are even supplied.

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

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

Annotations already declare readOnly/destructive/openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: the series is bucketed and split by sentiment signal, and the output points are intended as chart input. It does not mention defaults or auth, but the annotation bar is lower 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?

Two tightly packed sentences with no filler; the core purpose is front-loaded ahead of the usage/next-step hint.

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 unnecessary, and the description still sketches the shape (bucketed points). For a read-only trend tool with high param coverage, this is nearly complete; only the default granularity and low-quality exclusion behavior are left solely to the schema.

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

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

Schema description coverage is 80%, so the schema already documents since, until, granularity, and includeLowQuality. The description reinforces the granularity choice (day/week) and the signal split but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource+scope: 'Response volume over time for a project', then qualifies it with the bucketing (day/week) and the signal split. An agent can distinguish this from siblings like project_stats or channel_breakdown without opening a schema.

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

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

Explicitly says 'Use for trend / volume-over-time questions' and names the follow-up tool (generate_chart, line). It gives clear triggering context but no explicit when-not guidance or differentiation from adjacent stats tools such as project_stats.

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

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

Annotations already declare readOnlyHint/destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful content scope (sentiment, recommendations, mention counts, citable quotes), but since an output schema exists it adds little behavioral detail beyond that.

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

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

Compact: one front-loaded sentence describing scope and contents, plus a short prerequisite sentence. No filler, though the first sentence is a dense list.

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

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

With an output schema, full param coverage, and annotations present, the description only needs to convey purpose and routing. It does both, leaving little an agent would miss before calling it.

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

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

Schema coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description's note to resolve themeId via project_overview only echoes the schema's own 'from project_overview.themes' hint, adding no new syntax or format detail.

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 scope ('Drill into ONE theme of a project') and enumerates the contents returned, which distinguishes it from siblings like question_breakdown and project_overview. An agent can tell what it retrieves 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 routes the agent to project_overview to resolve theme ids, giving a clear prerequisite. It does not state when-not to use it or name an alternative for deeper theme exploration, but the 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 readOnlyHint=false and destructiveHint=true; the description adds real behavioral context beyond them — re-using an uploadId replaces the stored design (the destructive behavior), the HTML is temporarily hosted by TheySaid, and the mutation does not launch a test. It doesn't cover auth requirements or hosting lifetime, so not a full 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?

The fallback rationale and the network-block condition are front-loaded, and every sentence carries information (use case, params, overwrite semantics, return shape, negative scope). It is dense but slightly packed, with the return-shape and 'does not start a test' details competing for attention.

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 spell out return values, yet it summarizes { uploadId, previewUrl, nextStep } and names the follow-up tool, so an agent can chain correctly. Given only two undocumented params and full annotation coverage, the remaining gaps are minor edge cases rather than blocking 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 0%, so the description must carry the load, and it largely does: uploadId is framed as the hosting key whose reuse overwrites prior content, and html must be the complete, self-contained design HTML. It doesn't detail uploadId provenance or size limits, so it stops short of full compensation.

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 (upload/host) and resource (design snapshot) plus its precise scope: a fallback path used when the PUT to the uploadUrl from prepare_design_snapshot is blocked. It explicitly names the related sibling tools (prepare_design_snapshot, check_design_snapshot), so an agent can distinguish it without opening a schema.

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

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

Gives an explicit condition for use ("when the PUT ... is blocked by the environment's network, for example 'Host not in allowlist'"), identifies the primary alternative path, and adds a clear exclusion: "This tool does not start a test." Nothing about when-to-use 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 only cover the read-only/non-destructive safety profile; the description adds substantial traits beyond that: bounded server-side window, progress notifications emitted during the wait, `stillRunning` semantics on timeout, that re-invoking continues waiting, and how partial/failed runs are handled. This is exactly the operational context an annotations-only view lacks.

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 return-shape and edge-case details. Dense but every sentence carries information (notifications, stillRunning, re-call continuation, partial runs). Slightly sprawling for a two-parameter tool, but 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?

Covers the return contract (message, phase, results, resultsMarkdown), the timeout path, the continuation pattern, and degraded-run behavior, which is more than enough given an output schema already exists. An agent has everything needed to call and re-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 0%, so the description must carry parameter meaning. It explains maxWaitSeconds ('shortens a single wait') but does not define testId beyond implication. One of two parameters gets real semantics added, leaving an unmet gap against the low coverage baseline.

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

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

States a specific verb and resource (server-side wait for a usability test to finish) plus the mechanism (progress notifications, no polling). It implicitly distinguishes itself from get_test_results and get_test_status by being the blocking-wait variant. An agent can select it without opening a schema.

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

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

Gives clear usage context: 'so no polling is needed', 'long runs are normal', and 'calling wait_for_results again continues waiting' — behaviorally important for an agent choosing between waiting and polling. However it never explicitly names get_test_status as the non-blocking alternative or states when NOT to wait (e.g. for a quick status check).

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