Interbang

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

Annotations only indicate readOnlyHint=false. The description adds useful behavioral context by stating the return value ('Returns the new taskId') and the draft-state limitation, which goes beyond the simple mutation flag and helps the agent anticipate side effects.

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

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

The description is a single, compact sentence that front-loads the action and includes a parenthetical parameter list. Every word earns its place, with no redundancy or filler.

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

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

For a simple add operation with no output schema, the description covers purpose, return value, and an important precondition. It doesn't explain the semantics of optional fields, but given the tool's straightforward nature and the availability of sibling tools for context, this is acceptable.

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

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

The description lists all parameters (title, successCriteria, instruction, observationPoints, etc.) and marks title as required, matching the schema. However, with 0% schema description coverage, it doesn't explain the meaning of each field (e.g., what successCriteria represents), so it only partially compensates for the schema's lack of 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?

The description clearly states the action ('Add a task to a use case') with a specific verb and resource, distinguishing it from sibling tools like add_use_case, update_task, and delete_task. The scope is unambiguous.

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

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

It provides a clear precondition: 'Only works on use cases of PREPARING drafts,' which tells the agent when this tool is applicable. It doesn't explicitly name alternatives, but the constraint effectively guides usage by excluding non-draft use cases.

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 provide readOnlyHint=false, confirming a write operation. The description adds valuable behavioral context: the state requirement (PREPARING drafts) and the return of a useCaseId. No contradictions found. This exceeds the baseline set by annotations.

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

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

Three concise, front-loaded sentences deliver the core action, use case, return value, and constraint. No unnecessary words or 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?

The tool has no output schema, but the description explains the return value (useCaseId) and the prerequisite state (PREPARING drafts). It also indicates the sequential relationship with add_task. For a simple create operation with three parameters, this is reasonably complete, though it omits error handling or detailed side effects.

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 compensate. It clarifies that title is required and description is optional, but does not explicitly explain utId (though 'draft UT's scenario' implies it is the UT identifier). The description adds some meaning beyond the raw schema but leaves the utId parameter somewhat implicit.

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

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

The description clearly states the action: 'Add a use case to a draft UT's scenario' with specific verb and resource. It also distinguishes from sibling tools like add_task and update_use_case by focusing on creation of a use case within a draft scenario.

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 provides context for when to use the tool: it groups related tasks and returns a useCaseId for use with add_task. It also specifies a critical constraint: 'Only works on PREPARING drafts.' However, it does not explicitly contrast with update_use_case or delete_use_case, but the usage 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=true, so the tool's non-destructive nature is known. The description adds behavioral context about the default resolution of `against` (previous round) and the constraint that both rounds must be of the same UT. It does not disclose side effects or preconditions beyond what annotations and schema imply.

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

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

The description is two sentences: first defines the action and output, second gives parameter guidance. It is front-loaded and contains no filler or redundant information.

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

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

The tool has no output schema, so the description compensates by enumerating the comparison dimensions (per-use-case/per-task, deltas, problem/bug movement). It also explains the default behavior of `against` and the usage trigger. It does not cover edge cases like missing previous round, but the core information for an agent to select and invoke the tool is present.

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

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

Schema descriptions already cover both parameters with 100% coverage, including the 'usually later' convention and default behavior. The description essentially repeats the schema for `against` and adds only the contextual note that both rounds must be from the same UT, which is a minor enhancement.

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

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

The description clearly defines the action as 'Compares two rounds of the same UT' and enumerates specific metrics (success-rate, duration, rating deltas) and problem/bug movement. It distinguishes this from siblings by focusing on comparisons across rounds and using the term 'iterations'.

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 provides an explicit trigger: 'Use it when asked to compare rounds or see what changed across iterations.' It also clarifies parameter usage (pass later round as utId, against defaults to previous round). However, it does not name alternatives or when-not-to-use conditions.

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

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

Annotations only provide readOnlyHint=false. The description adds meaningful behavioral context: the created UT is a PREPARING draft, begins with an empty scenario, requires member access for team workspaces, and follows a specific lifecycle (draft → build → review → start sessions). This goes beyond the minimal annotation and helps the agent understand side effects and prerequisites.

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

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

The description is a single paragraph with three concise sentences. It front-loads the core purpose, then adds essential workflow and workspace details. Every sentence adds value—no fluff or repetition.

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

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

For a create tool with no output schema, the description covers the draft state, required/optional fields, workflow, and workspace selection. A minor gap is the lack of explicit mention of what the response contains (e.g., new UT ID), but the workflow implies subsequent interactions. Overall, it is sufficiently complete for operational use.

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

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

Schema description coverage is only 20% (workspaceId). The description compensates by mentioning all optional parameters (background, hypotheses, recruitmentCriteria) and clarifying workspaceId's default behavior and where to obtain it (from list_workspaces). It does not deeply explain each string field, but names are self-explanatory and the added context is valuable.

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

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

The description clearly states 'Create a usability test as a PREPARING draft' with a specific verb (create), resource (usability test), and state (PREPARING draft). It also lists required and optional fields, distinguishing it from sibling tools like add_task or update_ut by outlining the next steps 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?

The description provides explicit workflow guidance: 'It starts with an empty scenario — build it out with add_use_case / add_task, then a person reviews the draft and starts sessions in the app.' It also explains when to pass workspaceId (for team workspaces) and references list_workspaces as the source, giving clear when-to-use context and alternatives.

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

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

Annotations already declare destructiveHint true, but the description adds meaningful behavioral detail: 'the task and its fields are gone for good' and 'double-check the taskId (from get_ut)'. This goes beyond the raw annotation by explaining irreversibility and the safety precaution, though it doesn't describe error handling or return 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?

The description is two sentences: the first states the action and object, the second adds irreversibility and a warning. Every word earns its place, with no redundancy or filler.

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

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

For a simple destructive tool with one parameter, the description covers what it deletes, the critical safety check, and the draft-type constraint. Since destructiveHint is already annotated and no output schema exists, no further return-value explanation is necessary. The description is fully sufficient for an agent to use the tool safely.

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

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

The schema only lists taskId as a string with no description. The description compensates by explaining that taskId comes from get_ut and identifies a task within a draft UT, giving operational meaning to the single parameter. This is sufficient for correct invocation.

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 the specific verb 'Delete' and identifies the resource 'a task from a draft UT', clearly distinguishing it from sibling tools like delete_use_case. The additional constraint 'Only works on tasks of PREPARING drafts' further clarifies scope, making the purpose unmistakable.

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 advises verifying the taskId from get_ut before calling and notes the operation only works on PREPARING drafts, providing clear contextual guidance. However, it does not explicitly name alternative tools for other scenarios (e.g., update_task for modifications), so it lacks explicit when-not-to-use instructions.

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 indicate destructive intent, but the description adds irreversibility ('Irreversible'), scope ('including every task inside it'), and a state constraint ('Only works on PREPARING drafts'). These go beyond what annotations communicate and help the agent understand the full impact.

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

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

The description is compact and front-loaded. The first sentence states the core purpose, and the second packs necessary warnings and alternatives without fluff. Every clause contributes useful 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 destructive single-parameter tool, the description covers what is deleted, irreversibility, a verification step, the state constraint, and an alternative tool. No output schema is needed, and the information provided fully equips an agent to call the tool correctly.

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

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

The schema provides only the raw string type for useCaseId with 0% coverage. The description adds meaning by referring to 'the useCaseId' and suggesting to check its task list from get_ut, making it clear this is the identifier of the use case. It doesn't detail format, but the name is self-explanatory and the guidance is sufficient for a single simple parameter.

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

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

The description explicitly states 'Delete a use case from a draft UT, including every task inside it' with a specific verb and resource, and distinguishes from delete_task by noting it removes the entire use case including its tasks.

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 provides direct alternatives ('prefer delete_task when you only mean to remove a single task') and a state constraint ('Only works on PREPARING drafts'). It also advises verifying the useCaseId via get_ut before calling, acting as a clear precondition.

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

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

The annotations already declare readOnlyHint=true, and the description aligns with that by saying 'Reports'. It adds valuable detail about the exact data returned (email, scopes, readable workspace count), which goes beyond the annotation. It does not mention potential edge cases or error conditions, but for a zero-parameter read-only report this is adequate.

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

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

The description is two sentences, front-loaded with the primary verb 'Reports', and every phrase adds value. There is no redundancy or filler.

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

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

For a zero-parameter, read-only tool with no output schema, this description provides all essential information: what it reports, why to use it, and how it relates to the connection. No additional context is needed for correct invocation.

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

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

The input schema has zero parameters, so schema coverage is effectively 100%. The description adds context by explaining what the tool reports, which is sufficient given there is nothing to parameterize. The 0-param baseline of 4 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 clearly states the tool's purpose with a specific verb 'Reports' and defines exactly what it reports: the authenticated account email, granted scopes (ut:read / ut:write), and workspace count. This distinguishes it from sibling tools like list_workspaces or get_session, which serve different functions.

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 explicit usage guidance: 'Use it to check what this connection is allowed to do.' It clearly indicates when to invoke this tool, though it doesn't explicitly mention alternatives or when not to use it. Since the tool has a unique role and no parameters, this is sufficient.

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 readOnlyHint annotation covers the safety profile, so the description only needs to add non-obvious behavioral context. It lists the data categories returned, which is useful, but doesn't mention error handling, output format, or limitations. This is acceptable but not rich.

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

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

Single sentence, about 14 words, front-loaded with the main action ('Returns the quantitative analytics') and no extraneous wording. Perfectly concise and well-structured.

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

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

Given a one-parameter tool with read-only annotation and no output schema, the description covers the core purpose but lacks a description of the return format or detailed data structure. It is adequate for simple invocations but not fully complete for an agent.

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 provides only a bare 'utId' string with no description (0% coverage). The description's phrase 'for a UT' implies the parameter is a UT identifier, but it does not explain how to obtain the ID, expected format, or any constraints, leaving the agent to infer the semantics.

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

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

Uses specific verb 'Returns' with resource 'quantitative analytics for a UT' and enumerates content categories (overall counts, per-task success distribution, duration stats, variant info). Clearly distinguishes from siblings like get_transcript which would handle qualitative 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?

No explicit guidance on when to use this tool versus alternatives. The description merely states what it returns, leaving the agent to infer when quantitative analytics are needed without any exclusions or comparisons to sibling getters.

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 aligns with readOnlyHint (returns data, no side effects) and adds context by listing what data is included and specifying 'linked transcript excerpts' rather than a full transcript. However, it doesn't disclose the behavior of the includeFullTranscript parameter or any other nuances beyond the annotation.

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 concise sentence, front-loaded with the primary action, then a colon and a clear enumeration. Zero waste, easy to parse.

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

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

Given there's no output schema, the description does enumerate key return contents, but it misses the optional includeFullTranscript behavior and doesn't clarify how this relates to sibling tools. For a single GET-style tool, it's minimally adequate but has clear gaps.

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

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

With 0% schema description coverage, the description needs to explain the parameters. It doesn't mention sessionId semantics (though obvious from name) and completely omits the includeFullTranscript parameter, leaving the agent guessing about its purpose and effect. The phrase 'linked transcript excerpts' is the only hint, but it's insufficient.

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 specific verb ('Returns') and clearly defines the resource scope: everything about one session, enumerating its components (UT context, notes, task measurements, transcript excerpts). This distinguishes it from sibling tools like get_transcript or get_ut, which focus on single aspects.

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

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

The description implies this is the comprehensive way to retrieve all session data, but it doesn't explicitly state when to prefer this over sibling tools like get_transcript or get_quantitative_report. No exclusions or alternative guidance is provided.

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

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

Annotations already declare readOnlyHint=true, so the read-only behavior is known. The description adds context that it returns all segments (not paginated) and includes speakers/timestamps, but does not disclose any other behavioral traits such as error handling, rate limits, or special cases. It provides some added value without contradicting annotations.

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

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

The description is a single, front-loaded sentence with no redundancy. It includes the key details (full transcript, segments, speakers, timestamps) and no unnecessary words.

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

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

Given the tool's simplicity (one param, no output schema), the description covers the essential return content and scope. It does not mention error conditions, but that is not critical for a read-only retrieval tool. The annotation provides the safety context, and the description is adequate for selecting and invoking the tool.

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

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

Schema description coverage is 0%, yet the description only mentions 'for a session', which minimally clarifies the sessionId parameter. It does not explain the format, expected values, or any constraints beyond the schema's type and required flag. The description fails to meaningfully compensate for the lack of schema 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?

The description clearly states the verb 'Returns' and the specific resource 'full transcript (all segments, with speakers and timestamps)' for a session. This explicitly differentiates it from sibling tools like get_session by focusing on transcript segments, timestamps, and speakers.

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

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

The description implies usage: when you need the full transcript of a session. However, it does not explicitly state when to use this tool over alternatives like get_session or search_notes, nor does it provide any exclusion criteria. The guidance is minimal but 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?

The readOnlyHint annotation already communicates the read-only nature. The description adds that the output includes scenario use-case and task IDs for downstream editing, and lists the data categories returned. No contradiction, but no additional behavioral details 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?

Two sentences, front-loaded with a clear summary, and the second sentence provides actionable guidance without unnecessary detail. Every word earns its place.

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

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

With no output schema, the description lists main data categories and downstream use of IDs, but omits any explanation of the includeFullTranscript parameter and does not describe the return structure in detail. It is adequate for a read-only fetch but leaves gaps.

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

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

Schema description coverage is 0% and the tool description does not explain either utId or includeFullTranscript. The mention of IDs in the description refers to output values, not input parameters, leaving the optional boolean completely undocumented.

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

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

The description explicitly states 'Returns everything about one UT' and enumerates the contents (scenario, quantitative results, sessions with notes and transcript excerpts), making it distinct from sibling tools like get_session or get_quantitative_report.

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 clearly implies when to use this tool (when you need full context of a single UT) and gives actionable guidance to pass output IDs to add_task/update_task for editing. No explicit exclusions, 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 provide readOnlyHint=true, so the safety profile is covered. The description adds the cross-workspace scope ('every workspace you can access') and the optional status filter, but does not disclose pagination behavior or return format. With annotations, this is adequate but not rich.

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

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

The description is only two sentences, front-loads the primary purpose, and includes only essential details. No filler or repetition of schema 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?

For a simple list tool with no output schema, the description adequately conveys the core behavior and key filter. It omits the limit parameter's behavior and any pagination details, but these are minor given the tool's low complexity.

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 compensate. It explicitly lists the status filter values and optionality, but does not explain the limit parameter. The description partially covers the parameters, leaving the limit's effect on results 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?

The description clearly states the tool lists usability tests across all accessible workspaces, using a specific verb ('Lists') and resource ('usability tests'). It distinguishes from sibling tools like get_ut (single UT) and create_ut by indicating it is the 'usual starting point for finding a UT'.

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 provides clear usage context ('usual starting point for finding a UT') but does not explicitly mention when not to use it or name alternatives. Context signals show siblings like get_ut, but no explicit comparison is made.

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 the description adds behavioral context by stating that the tool returns the user's role in each workspace, which implies write access levels (MEMBER or OWNER). This goes beyond the annotation by clarifying the return content and its significance for write operations.

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

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

The description is two sentences, front-loaded with the main purpose, and every sentence adds value. It is concise without unnecessary fluff.

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

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

There is no output schema, so the description carries the responsibility of explaining the return value. It clearly states that workspaces and roles are returned, and it also explains the relationship to other tools and write access. This is complete for a simple list tool with no parameters.

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 schema is trivially covered. The description provides meaning about what the tool returns (workspaces with roles), which is useful given the empty input schema. Baseline 4 for zero parameters is appropriate and no further parameter explanation 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 uses the specific verb 'lists' and clearly identifies the resource as workspaces with the scope 'every workspace you belong to'. It also mentions the additional detail of returning the user's role in each, distinguishing this tool from siblings that focus on other entities.

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 provides clear context for when to use this tool: to discover which workspaces the other tools can reach and which ones the user can write to based on membership. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of full guidance.

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

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

Annotations only provide readOnlyHint=true. The description adds valuable behavioral details: substring matching is case-insensitive, results cap at 200, and returned data includes use-case context. These go well beyond the annotation and inform agent expectations.

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

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

The description is two sentences, front-loaded with the core purpose. Filters are neatly formatted in backticks, and the return behavior is stated compactly. No wasted words.

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 search tool with 5 optional parameters and no output schema, the description covers purpose, filter semantics, result limit, and return context. It lacks exact definitions of the ID parameters and precise return structure, but remains largely complete for an AI agent.

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 is the sole source for parameter meaning. It explains `query` (substring, case-insensitive) and `tag` (enum values), but `utId`, `sessionId`, and `useCaseId` are only named with no explanation of what they represent or how they filter. This leaves significant gaps.

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

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

The description clearly states the action ('Searches') and resource ('notes you can read'), adding a scope limitation. It distinguishes itself from sibling getters like get_ut or get_session by being a cross-note search, not a single-entity retrieval.

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

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

Provides clear context: supports filtering by query/tag/IDs and returns use-case context for grouping. However, it does not explicitly state when to avoid this tool or mention alternatives like list_uts or get_session as substitutes for specific lookups.

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 indicate idempotentHint=true and readOnlyHint=false, and the description adds valuable context about what the fields represent (moderator's intro/wrap-up) and the PREPARING draft restriction. It does not contradict annotations and adds behavioral detail beyond them.

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

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

The description is concise, front-loaded with the key action, and uses every sentence meaningfully. It fits in two sentences with no redundancy or filler.

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

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

For a simple update tool with no output schema, the description fully covers the tool's purpose, parameter usage, and key constraint (PREPARING drafts). It is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema descriptions are absent (0% coverage), but the description compensates by explaining openingGuide and closingGuide ('moderator's intro and wrap-up script') and by instructing to pass them optionally. utId is self-evident from the tool context, though not explicitly described.

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 specific verb+resource construct: 'Set a draft UT's scenario opening and/or closing guide'. It clearly differentiates the tool from update_task and update_use_case by clarifying this is session-level framing, not a task.

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 provides clear context for use: it instructs to 'Pass openingGuide and/or closingGuide' and states 'Only works on PREPARING drafts'. It also explicitly says 'not a task', helping distinguish it from sibling tools, though it doesn't name exact alternatives.

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

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

Annotations already provide readOnlyHint=false and idempotentHint=true. The description adds the draft-status constraint and the partial-update nature ('any of'). However, it does not explain side effects, permission requirements, or what happens if the task is not in PREPARING state. Some behavioral context is added but not extensive.

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

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

The description is extremely concise: one sentence with the core action plus a parenthetical list of editable fields, and a second sentence stating a key constraint. There is no wasted language, and the most important information is front-loaded.

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

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

Given the tool has 8 parameters, no output schema, and only basic annotations, the description could be more complete. It covers purpose and the draft constraint, but omits details like return values, error handling, and whether partial updates are true (e.g., unspecified fields remain unchanged). It is adequate for a simple update but not fully comprehensive.

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

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

The schema has 0% descriptor coverage, so the description must compensate. It lists the updatable fields, matching the schema property names, which helps the agent know which are editable. However, it does not explain the meaning of each field (e.g., successCriteria, probingQuestions) beyond their names, nor the required taskId parameter. Partial compensation only.

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

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

The description clearly specifies the verb 'Update' and the resource 'a task in a draft UT', and enumerates the exact fields that can be modified. This distinguishes it from sibling tools like add_task and update_ut, which target different resources or operations. The scope is unambiguous.

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

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

The description gives a clear usage context: use this to update task fields within a draft UT, and explicitly states a constraint ('Only works on tasks of PREPARING drafts'). It does not explicitly name alternative tools for non-PREPARING states, but the draft constraint implies when it should be used. This is sufficient guidance for most cases.

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

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

The annotations already indicate readOnlyHint=false and idempotentHint=true. The description adds meaningful behavioral context beyond annotations by restricting operation to PREPARING drafts and stating which fields can be modified. It does not contradict annotations and provides useful constraints, though it does not discuss errors or reversibility.

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

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

The description is concise at three sentences, front-loaded with the primary action. The sentence 'Use cases group related tasks' adds useful domain context, and the constraint about PREPARING drafts is essential. No wasted words.

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

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

The tool is simple (3 params, no output schema) and the description covers the core operation, scope, and restrictions. It does not mention what happens if the draft is not in PREPARING state or the return value, but for this low complexity and given annotations, it is adequate and sufficiently complete.

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

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

With 0% schema description coverage, the description must compensate. It explains that title and description are the updatable fields ('any of: title, description'), which adds meaning beyond the raw schema. However, it does not describe the useCaseId parameter's format or purpose, leaving some gaps.

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

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

The description clearly states the action ('Update a use case') and the resource scope ('in a draft UT'), distinguishing it from siblings like update_ut, update_task, and add_use_case. It also specifies the updatable fields ('title, description'), making the purpose unambiguous.

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

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

The description provides a clear context: it is for updating title/description of use cases and includes a specific exclusion ('Only works on use cases of PREPARING drafts'). However, it does not explicitly name alternative tools for when this tool should not be used, so it falls short of 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?

The description adds valuable behavioral context beyond the annotations: it restricts updates to PREPARING drafts, disallows status changes, and clarifies that only listed metadata fields can be updated. This complements the readOnlyHint=false and idempotentHint=true annotations without contradiction.

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

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

The description is two sentences with clear front-loading of the action and resource, followed by a concise constraint. Every word earns its place, and it is free of 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 tool with 5 parameters and no output schema, the description covers the essential aspects: what it does, which fields can be updated, and the state constraint. It does not detail return values or error behavior, but these are less critical for an update operation. Overall, it provides sufficient context for correct usage.

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 compensate for missing parameter details. It lists the updatable fields but provides no semantic explanation for each (e.g., what 'background' or 'recruitmentCriteria' means), relying on self-explanatory names. The description adds no meaningful parameter-level guidance beyond the field names.

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

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

The description clearly states the action ('Update'), the resource ('a draft UT's metadata'), and explicitly lists the modifiable fields (title, background, hypotheses, recruitmentCriteria). It also distinguishes itself from sibling tools like create_ut and get_ut by focusing on updating metadata only.

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 provides explicit guidance on when the tool is applicable: only for PREPARING drafts, and explicitly states it cannot change status or edit running/finished UTs. This gives clear when-to-use and when-not-to-use context, though it does not name alternative tools.

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