Survey Solutions MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.2.7
Disambiguation1/5
Several tools are nearly indistinguishable: multiple export/combine workflow wrappers overlap heavily, and at least four tools (qc_generate_check_plan, plan_hq_auto_approval, apply_hq_auto_approval, summarize_hq_review_queue) share the identical description 'Build or run a guarded QC/support workflow.' An agent selecting between these will frequently pick the wrong one.
Naming Consistency4/5
The vast majority of tool names follow a consistent snake_case verb-first or domain-prefixed pattern (list_, create_, get_, set_, qc_, etc.). Minor deviations exist, such as noun-style names like survey_solutions_orientation, openapi_operation, and rest_request, but the overall pattern is readable and predictable.
Tool Count1/5
At 123 tools, this server vastly exceeds any reasonable tool surface for an agent to navigate reliably. Many tools are high-level workflow wrappers that overlap with more basic operations, making the count feel padded rather than curated.
Completeness4/5
The tool set covers an impressively broad lifecycle: workspaces, users, questionnaires, assignments, interviews, exports, QC checks, approvals, and raw API escape hatches. Minor gaps exist, such as no direct user update or questionnaire delete/import endpoint, but those can be worked around via instructions or raw API tools.
Average 3.2/5 across 123 of 123 tools scored. Lowest: 1.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- Last stable release on July 22, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It does mention that it returns 'next steps,' but it does not explain side effects, whether the operation is asynchronous, what the response format is, or that it may initiate a long-running job. The description is too thin to give an agent confidence in the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, but its brevity is not effective conciseness—it under-specifies to the point of being unhelpful. The structure also front-loads the vague 'High-level workflow' label rather than concrete usage details, wasting the little space it has.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters (1 required, 1 enum), no annotations, and no output schema, the description is completely inadequate. It fails to explain the workflow steps, the expected return value, or how 'download next steps' relate to export jobs. An agent cannot reliably call this tool correctly based on the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to any of the 5 parameters. It does not explain what questionnaire_identity refers to, what export_type options imply, or how output_path is used. The description provides zero added value over the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('start an export') for a specific resource ('one questionnaire'), but the second half ('return export job/download next steps') is vague and does not distinguish this tool from sibling tools like start_export or export_all_formats. It conveys a high-level wrapper but lacks specific scope or differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, conditions, or exclusions. The label 'High-level workflow' hints at a wrapper but offers no explicit routing or context for when it should be selected over more direct export tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only says 'guarded QC/support workflow' without stating whether the tool mutates approval state, what confirm_plan_id is for, what side effects occur, or what outputs to expect. The x_suso_qc metadata in the schema is not part of the tool description and does not compensate for this lack of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise in length but under-specified to the point of being uninformative. A single vague sentence does not earn its place because it conveys almost no actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has 8 parameters, nested objects, no output schema, no annotations, and a large sibling set including plan_hq_auto_approval and numerous QC tools. The one-line description is nowhere near sufficient for an agent to understand, prepare, and safely invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool description says nothing about parameters. Schema description coverage is only 50%, and the two required parameters 'plan' and 'confirm_plan_id' have no descriptions, so an agent cannot determine what values are expected. The description adds no semantic value beyond the incomplete schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Build or run a guarded QC/support workflow' but does not explain what applying HQ auto-approval actually does. The two verbs 'build or run' create ambiguity and the description does not distinguish this tool from sibling plan_hq_auto_approval or the many qc_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus alternatives such as plan_hq_auto_approval, apply_qc_feedback_batch, or hq_approve_interview. No prerequisites, exclusions, or decision criteria are provided; the agent is left to infer entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It does add some real behavioral context: 'guarded', the exclusion rule about not_evaluated, and the explicit warning to review output status/counts to see whether analysis was performed. However, it never discloses side effects such as whether approvals are actually applied, whether changes are reversible, or what authorization is required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The one-line description is terse, but it achieves brevity by omitting essential meaning. The schema then repeats 'depends on workflow' multiple times and points to empty threshold properties, so the overall definition is not a well-structured, information-dense description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter workflow tool with no output schema and no annotations, this definition is incomplete. It leaves unclear how 'build' differs from 'run', what a valid plan looks like, how confirm_plan_id is obtained, and what side effects the workflow has. The x_suso_qc output contract and exclusion rule provide some structure, but the essential call semantics are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, and the description adds no parameter-level meaning. Several key parameters—plan, profile, confirm_plan_id, questionnaire_identity—are completely undocumented, while others are hand-waved as 'depends on workflow'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Build or run a guarded QC/support workflow', which identifies a general action and domain, but the resource is abstract and the tool name's 'auto_approval' behavior is never explained. It does not distinguish this tool from the sibling apply_hq_auto_approval, which sounds like the actual executor of the same concept.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, prerequisites, or alternatives are stated. The schema's note to 'review output status and counts' is a verification hint, not guidance for choosing this tool over apply_hq_auto_approval or the other QC siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It does disclose that the workflow is a scaffold and that the agent should 'review output status and counts to see whether analysis was performed,' plus an exclusion rule about status=not_evaluated, which is useful. However, it remains unclear what side effects or mutations may occur, what triggers analysis, or what 'guarded' means operationally.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The top-level description is short and front-loaded, but the content is under-specified rather than efficiently informative. The schema description repeats the 'workflow scaffold' phrase and relies on 'Depends on workflow' placeholders instead of structured, helpful details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 8 params, nested objects, no output schema, and no annotations, the description is far too minimal to support correct invocation. Missing are a clear output contract in the description, input requirements, workflow semantics, and differentiation from the many QC and export siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, so the description must compensate, but it adds little parameter-level meaning. It does clarify that rules need variables/condition/expected relationship and that export_path must point to a readable export, yet plan, profile, confirm_plan_id, and questionnaire_identity remain essentially unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Build or run a guarded QC/support workflow' is vague about what the tool actually produces or does; it does not clearly state that the tool summarizes an HQ review queue. The term 'guarded workflow' is ambiguous and fails to distinguish this from numerous sibling QC tools such as summarize_export_qc or qc_logical_consistency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives; the description only says 'build or run' with no context for selecting a mode. It does not mention any prerequisites, exclusions, or scenarios where another sibling would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It only indicates the operation is a read, but it does not disclose the response shape, pagination behavior, required permissions, or whether the report content depends on the active profile or workspace.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no wasted words, but it is under-specified rather than usefully concise. It skips essential detail that an agent needs to select and invoke the tool correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and a generic query parameter, the description is far from complete. It does not explain what report is returned, how to build the query, what profile means, or how the result relates to sibling statistics tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters, 'query' and 'profile', with 0% schema description coverage. The description merely says 'using query parameters' and adds no meaning to either parameter, leaving an agent with no idea what keys the query object should contain or how 'profile' is used.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'read a built-in Survey Solutions statistics report.' It is understandable at a high level, though it does not specify which built-in report or how it differs from closely related siblings like list_statistics_questionnaires or get_interview_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus the many statistics-related siblings. The phrase 'using query parameters' hints at some flexibility but provides no context, prerequisites, or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether the tool makes network calls, reads local files, has side effects, or requires specific permissions. The phrase 'downloaded version exports or available questionnaire metadata' suggests it may work with local files or remote data, but the mechanics are undefined. This is a significant gap for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and is front-loaded with the action, which is good. However, it is too terse to be useful—it omits parameter explanations and usage context. While concise, it does not earn its keep by providing sufficient information, so it falls short of a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and 0% schema description coverage, the description must be exceptionally thorough. Instead, it offers only a minimal purpose statement. The agent cannot determine required inputs, expected output, or behavioral characteristics, making the definition critically incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters. It does not mention any of the three parameters (profile, export_paths, questionnaire_id_or_title), nor their roles or relationships. An agent has no idea how to populate these fields or what each controls, making correct invocation impossible without external knowledge.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Compare schemas') and a resource scope ('for downloaded version exports or available questionnaire metadata'). It distinguishes itself from sibling 'compare_questionnaire_versions' by focusing on schemas rather than version content, making its purpose reasonably clear. However, it does not specify what 'schemas' refers to (e.g., XSD, JSON structure) or the output format, which adds minor ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like compare_questionnaire_versions or export_and_combine_questionnaire_versions. It does not mention prerequisites (e.g., whether export_paths must reference files from a prior export) or contexts where schema comparison is needed. The agent is left to infer usage without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. 'Build or run' implies possible execution, but it does not say whether running a workflow mutates data, requires confirmation, performs only a dry run, or what safeguards 'guarded' actually enforces. The x_suso_qc metadata hints that output status and counts must be reviewed to know whether analysis was performed, but that context is not surfaced in the visible description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, so it is structurally clean. However, the brevity comes from omitting essential operational detail rather than from distilling rich information, making it closer to an under-specified stub than a genuinely effective definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex, polymorphic tool with 8 parameters, nested objects, no annotations, and no output schema. The description tells an agent almost nothing about required inputs, expected output, guardrail behavior, or when to invoke it. The x_suso_qc outputContract provides some scaffolding, but it is buried in the schema and does not compensate for the missing operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, and the description adds no parameter-level meaning. Parameters such as plan, profile, confirm_plan_id, and questionnaire_identity are left unexplained, while the description offers no help in understanding how plan, rules, thresholds, and variables relate to each other. An agent would struggle to construct a correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Build or run a guarded QC/support workflow,' which names a general action and resource, but it never specifies what a 'check plan' is, which QC workflows are supported, or what 'guarded' means. The schema's methodologySummary ('Workflow scaffold...') adds only a small hint and does not define a concrete deliverable or differentiate this from the many sibling qc_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not state when to use this tool, what prerequisites exist, or how it relates to alternatives such as qc_logical_consistency, summarize_export_qc, or the other QC-focused siblings. There are no exclusions, conditions, or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It does disclose the required permissions ('fieldwork_write/admin_write') and the confirmation safeguard ('exact assignment confirmation'), which is useful. However, it does not reveal side effects, whether the change is reversible, what happens to the assignment, or what the response looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loads the main action, but it is under-specified rather than appropriately sized. For a mutation tool with five undocumented parameters, the terse two-sentence structure omits essential information, so efficiency comes at the cost of usefulness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters, no annotations, no output schema, and a mutating operation, this description is not complete enough. It fails to define allowed statuses, explain confirmation semantics, clarify comment/profile purposes, or describe expected behavior, leaving critical gaps for an agent invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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, but it only hints at confirm_assignment_id through 'exact assignment confirmation.' It does not explain valid status values, the role of comment, or what profile controls, leaving an agent unable to construct a correct call confidently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action 'Change assignment status,' identifying the resource and verb, and is distinguishable from siblings like change_assignment_quantity and change_assignment_target_area. However, it never defines what 'status' values are supported, leaving the core purpose vague for an agent that must decide between this and archive/unarchive, which are also status-like mutations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as archive_assignment, unarchive_assignment, or assign_assignment. The only contextual hint is the permission requirement, which says nothing about the conditions that should trigger this tool rather than a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral disclosure burden. It only implies a read-only compare-and-summarize operation and notes API visibility, but it does not describe output format, failure modes, profile requirements, or whether anything is mutated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence that front-loads the core purpose and avoids filler. It is concise and readable, though it sacrifices useful details for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and a highly similar sibling tool, this description leaves out too much: parameter semantics, return shape, and when to prefer this over compare_questionnaire_version_schemas. It is minimally adequate but not complete for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description never mentions either parameter. It does not clarify that questionnaire_id_or_title accepts an ID or title, nor what profile means, leaving an agent without any parameter-level guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: compare known questionnaire version metadata from Headquarters and summarize API-visible differences. It identifies the resource (questionnaire versions) and output type (a differences summary), though it does not explicitly differentiate itself from the sibling compare_questionnaire_version_schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as compare_questionnaire_version_schemas or the export/combine tools. The description only says what it does; it does not state exclusions, prerequisites, or selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It only says exports are 'started' but does not mention whether the operation is asynchronous, how many jobs are created, what side effects occur, whether setup is required, or how results are retrieved. This is minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the action and object front-loaded. There is no filler or redundancy. However, it is so terse that it omits important contextual and parameter information, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five parameters, no annotations, no output schema, and a rich sibling landscape, the description is far too thin. It gives the basic action but not enough context about job handling, format specification, or how this relates to the many export-related sibling tools. Some context exists, but significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and none of the five parameters are explained. The description does not clarify the expected format of questionnaire_identity, the accepted values in export_types, the role of profile, output_dir, or interview_status. It fails to compensate for the complete lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Start exports for one questionnaire in multiple formats.' It clearly identifies the tool as initiating multi-format exports for a single questionnaire, which distinguishes it from broader sibling tools that combine versions or formats. However, it doesn't explicitly name a sibling to differentiate from.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like export_and_combine_all_versions_all_formats or start_export. The phrase 'one questionnaire' implies a scope constraint, but there are no explicit usage conditions, exclusions, or comparisons to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It indicates an export-starting action but does not mention whether jobs are queued, how progress or results are reported, whether previous exports are overwritten, or what permissions are needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler and the core action is front-loaded. However, it is syntactically awkward ('versions of a questionnaire title or ID') and too terse to serve as an adequate spec for a five-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, no annotation coverage, and no parameter documentation. The description explains neither what happens after exports are started, how to monitor or retrieve them, nor how to set the remaining parameters, leaving an agent with significant guesswork.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 for all parameters. It only hints at the meaning of questionnaire_id_or_title via 'title or ID'; profile, output_dir, export_type, and interview_status are left unexplained beyond their bare names and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Start exports') and a clear resource scope ('all imported versions of a questionnaire title or ID'). It does not name or contrast any sibling tool, but the scope is concrete enough to distinguish it from tools like export_all_formats or export_and_combine_questionnaire_versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool vs. the many export-related siblings. The phrase 'all imported versions' implies a use case, but there is no when-to-use, when-not-to-use, or alternative recommendation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions one safety behavior (not exposing unnecessary free text) but omits critical details such as the required export type, exclusion of empty comments, output structure, and any side effects or processing behavior. The schema has exclusion rules, but the description does not reflect them, so transparency is low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, front-loading the core purpose. It is concise, but its brevity borders on under-specification for a tool with eight parameters. Still, for conciseness and structure, it is efficiently written, though it lacks any structured breakdown of usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
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 annotations, no output schema, and only 50% schema description coverage, the one-line description is seriously inadequate. It does not mention required export types, minimum data requirements, output contract, or exclusions, leaving agents without enough information to invoke the tool correctly. This is a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter schema already explains some parameters (rules, variables, thresholds, export_path), but coverage is only 50%. The description adds no parameter-specific meaning beyond the one-line summary. For parameters like plan, profile, confirm_plan_id, and questionnaire_identity, the description provides no additional context, failing to compensate for the schema's gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Summarize') and a resource ('comment themes'), and adds a meaningful constraint about not exposing unnecessary free text. It is clear what the tool does, but it does not explicitly differentiate it from sibling tools like summarize_export_qc or other QC analyzers, leaving some room for ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention of prerequisites (e.g., required export type or minimum data), and no exclusions or conditions. The description implies a use case but does not state it explicitly, leaving the agent to infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only restates the flagging intent. It does not disclose that values are counted and compared to thresholds, that structurally non-applicable values are excluded, or what the output contract looks like; those details are in schema metadata rather than the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single scannable sentence, which is concise. However, it opens with 'qc_targeted_missingness:' duplicating the tool name, and the phrase 'specific high-priority variables or sections' is too vague to carry much informative weight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given eight parameters, no annotations, and no output schema, a one-sentence description is not complete enough for confident invocation. The x_suso_qc metadata provides useful output and methodology hints, but the description itself does not surface them, and there is no guidance on how the nested plan/rules/thresholds objects should be structured for this specific QC check.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description maps only to the high-level 'variables or sections' idea and does not clarify any of the eight parameters. Schema coverage is 50%, and the undocumented parameters (plan, profile, confirm_plan_id, questionnaire_identity) are not compensated for by the description, leaving an agent without enough semantic guidance for invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Flag missingness in specific high-priority variables or sections,' which conveys the tool's core purpose and narrows its scope relative to general QC tools. However, it does not explicitly differentiate it from sibling QC tools such as qc_nonresponse_by_enumerator, and 'high-priority' is left vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. There is no mention of when targeted missingness is preferable to qc_nonresponse_by_enumerator or qc_response_distribution_shift, and the only operational constraints ('Required export type: Tabular', 'Minimum data: One or more variables') live in the schema rather than the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions permission requirements but does not disclose the consequences of archiving, whether the operation is reversible, or any side effects. This is a meaningful gap for a state-changing operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences with no filler. The primary action is front-loaded, and the permission requirement is the only additional context provided, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations and no output schema, yet the description is minimal. Critical details such as the meaning of confirm_assignment_id, the effect of archiving, and the relationship to unarchive_assignment are absent. The description is not complete enough for an agent to invoke this tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters. In particular, the required confirm_assignment_id parameter is not described at all, leaving the agent to guess whether it must match assignment_id or serve some other confirmation purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Archive an assignment.' This is unambiguous about what the tool does. However, it does not explicitly distinguish this from the sibling unarchive_assignment, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a permission prerequisite but no guidance on when to use this tool versus alternatives such as unarchive_assignment, change_assignment_status, or downsize_assignment. It provides context but no decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does state an authorization requirement ('Requires admin_write permission'), which is useful, but it does not explain whether disabling is reversible, what side effects occur, or how it affects workspace users and related data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely compact: the first sentence names the action and target, and the second provides the permission requirement. There is no filler or redundancy, and the key purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating administrative tool with no annotations, no output schema, and a vague 'profile' parameter, this description is too sparse. It omits the consequences of disabling, reversibility, behavioral expectations, and any alternative routing, leaving the agent without enough context to use it safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning for either parameter. 'workspace_name' is intuitive from the name, but 'profile' is entirely unexplained, and the description does not clarify how or whether these parameters relate to the disabling operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Disable') and a specific resource ('Survey Solutions workspace'), so an agent can tell this apart from enable_workspace or delete_workspace by the verb alone. It does not explicitly contrast with sibling workspace-management tools, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use disable_workspace versus enable_workspace, update_workspace, or delete_workspace. The only usage-related information is the admin_write permission requirement, which is a prerequisite rather than a decision rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose the side effect of starting exports and clarifies that the result is a plan plus pending download steps rather than completed downloads. However, it omits details such as whether exports run asynchronously, how partial failures are handled, or what the returned combine plan actually contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core behavior. It is efficient, though its brevity leaves important semantic gaps.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a high-level workflow with five parameters, no output schema, and no annotations, so the description must carry more weight. One sentence does not tell an agent what the combine plan looks like, how to perform the pending download steps, or what the parameters control.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate for any parameter. None of profile, output_dir, export_type, interview_status, or questionnaire_id_or_title are explained beyond the bare schema properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a workflow that starts exports for all versions and returns a combine plan plus pending download steps. This is specific enough to convey the tool's function, though it does not explicitly differentiate itself from close siblings like export_all_questionnaire_versions or export_and_combine_all_versions_all_formats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool instead of related alternatives. It does not mention prerequisites, or contrast itself with export_all_questionnaire_versions, combine_versioned_exports, or export_and_combine_all_versions_all_formats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It does not state whether the operation is read-only, what output format is produced, what permissions are needed, or whether any side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant phrasing. Every word contributes to the general purpose, though significant detail is missing in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generation tool with no output schema, no annotations, and zero parameter-level documentation, this description is incomplete. An agent would not know what the generated instructions look like, how to interpret the inputs, or what results to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 for parameters like profile, workspace_name, and interviewer_usernames. It only loosely refers to 'workspace/server/user details' and does not explain what 'profile' means or how interviewer_usernames affect the generated instructions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'generate practical tablet setup instructions' from workspace/server/user details. This makes the tool's purpose reasonably clear and distinguishes it from siblings like generate_fieldwork_brief, though it does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as generate_fieldwork_brief or setup_questionnaire_fieldwork_project. The description implies a purpose but provides no when-to-use or when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Inspect', which implies read-only behavior, but it does not describe the return format, whether results are paginated, or whether the conditional Headquarters build affects the output. This is thin coverage for a tool with no structured behavioral metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant filler, and the core action is front-loaded. The conditional clause is slightly awkward but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotation context, so the description must explain what the agent should expect. It does not mention the shape of the history, whether profile is needed to access certain histories, or what conditions might make the history unavailable. An agent could call the tool but would be uncertain about the response and edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 fails to explain the purpose of the 'profile' parameter and does not explicitly state that assignment_id identifies the assignment whose history is inspected. The property names are self-explanatory to a degree, but the description adds little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Inspect' combined with the resource 'assignment history/changes' clearly states what the tool does. It is distinct from the sibling get_assignment, which presumably returns current assignment state, though it does not explicitly name that alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'where the active Headquarters build exposes assignment history' provides a limited availability condition, but there is no guidance on when to prefer this tool over similar siblings like get_assignment or get_interview_history. No alternatives or exclusions are described.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for disclosing behavior. It does not mention pagination behavior, default ordering, whether archived assignments are included, profile/workspace scoping, rate limits, or what the response contains. Saying 'List... assignments' is minimal and does not go beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the primary purpose. The second sentence is not strictly operational but provides compact domain context. No redundant or verbose phrasing is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with four parameters, a nested query object, no annotations, and no output schema, the description is too thin. It omits essential usage context such as how to paginate, what fields can be filtered via query, how profile affects results, and what the returned assignment objects look like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents limit, offset, and query, but the description adds no operational meaning to these parameters. The profile parameter has no schema description and is entirely unexplained in the tool description. The reference to 'quantities and rules' is conceptual and does not help an agent understand query filtering or parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-plus-resource statement, 'List Survey Solutions assignments,' which clearly identifies the operation and resource. The follow-up sentence provides useful domain context about what assignments are. However, it does not explicitly differentiate this list operation from related siblings like get_assignment or get_assignment_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use list_assignments versus alternatives such as get_assignment, create_assignment, or get_assignment_history. No conditions, exclusions, or recommended scenarios are provided, so the agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It indicates that the tool produces counts/statuses, but it does not state whether the operation is read-only, whether it requires any data to already be staged, how aggregation works, or what the returned structure looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler and gets to the point immediately. It is efficient and front-loaded, though it sacrifices important operational detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotation support, yet the description does not explain return values, parameter meanings, or the relationship between the four inputs. For a tool with four parameters and no structured metadata, this is insufficient for an agent to invoke it correctly and confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and all four parameters are undocumented in the schema. The description only helps infer that interviewer_ids relates to interviewers; from_utc, to_utc, and profile are left entirely to guesswork, so the description does not adequately compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly names the action ('summarize'), the resource ('interview counts/statuses for one or more interviewers'), and the data source ('available interview list data'). It is easy to understand what the tool does, but it does not explicitly distinguish itself from sibling tools such as summarize_fieldwork_status or investigate_interviewer_anomaly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives, no explicit exclusions, and no named sibling tools. The phrase 'from available interview list data' only implies a data source; it does not explain the conditions that would make this tool the right choice over similar summary or QC tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates a read-style lookup and emphasizes exact user ID matching, but it does not mention auth requirements, error behavior, whether non-interviewer users are accepted, or what 'details' includes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to conveying the core lookup operation, making it an appropriately concise definition for its apparent simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no annotations and no output schema, so the description must carry more weight. Saying 'details' is vague, and the description does not clarify what fields are returned, whether the interviewee profile is needed, or how this tool relates to user/supervisor lookup tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 for the input schema. It clarifies that user_id must be exact, but it leaves the optional 'profile' parameter completely unexplained and adds no meaning about relationships, formats, or allowed values beyond the property names themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Get interviewer details' by 'exact user ID.' It is specific about the lookup mechanism, but it does not explicitly differentiate this tool from siblings like get_user, get_supervisor, or list_supervisor_interviewers, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as get_user or list_supervisor_interviewers. It implies a direct lookup by user_id, but there are no stated exclusions, prerequisites, or context for choosing this tool over a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden of behavioral disclosure. It indicates the operation is a read, but does not explain output shape, pagination, date-window formatting, timezone edge cases, or any access constraints. 'Where supported' is vague and leaves the agent unsure about failure modes or capability detection.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that leads with the core action and resource before adding the date-window caveat. It contains no filler or redundant information, and every clause adds meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four undocumented parameters, no output schema, no annotations, and a large sibling list, the description is too thin for an agent to invoke the tool reliably. It lacks parameter details, return value expectations, and any mention of limits or special cases. The 'where supported' caveat is too vague without a way to determine support.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 for the four undocumented parameters. It only hints at 'UTC date window', which loosely maps to from_utc and to_utc, but it says nothing about interviewer_id or profile. The agent cannot determine the meaning, format, or optionality of most parameters from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Read') and the resource ('interviewer actions/audit log'), and the resource name distinguishes it from related tools like get_interviewer or get_interview_history. However, it does not explicitly contrast with siblings such as investigate_interviewer_anomaly or summarize_interviewer_activity, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. It does not mention whether it is preferred for debugging, auditing, or anomaly investigation, nor does it state any conditions that would make another tool more appropriate. The phrase 'where supported' hints at environment-dependent availability but provides no actionable selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a read operation but does not disclose permissions, error behavior (e.g., not found), or whether only supervisor records are returned. No additional behavioral traits are given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence, front-loaded with verb and resource, with no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool, the essentials are present, but the optional profile parameter is unexplained and there's no context on how this differs from other user-role lookups. The description is minimal and lacks detail on the profile parameter or return expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the user_id parameter as requiring an exact ID, but the profile parameter is entirely unexplained. With 0% schema description coverage, the description should compensate for both parameters but only covers one.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get'), resource ('supervisor details'), and key identifier ('exact user ID'). It distinguishes from list_supervisors by specifying an exact ID lookup, and from get_user by targeting supervisors specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool over siblings like list_supervisors or get_user, nor any exclusions or conditions. It is purely a statement of function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It only says 'Get details' without explaining what details are returned, whether the operation is read-only, how missing or invalid IDs are handled, or whether both supervisor and interviewer identifiers are accepted. The behavioral disclosure is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy or filler. Every word contributes to stating the core function, and it is appropriately sized for a simple lookup tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description should cover return expectations and parameter roles. 'Get details' is too vague about what an agent should expect, and the profile parameter is entirely undocumented. The description is adequate at a high level but incomplete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 maps 'by ID' to user_id, which is helpful, but the optional 'profile' parameter is completely unexplained. An agent has no clue what values profile accepts or what effect it has on the response.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a resource ('details for a supervisor or interviewer user'), and the lookup method ('by ID'). It clearly describes what the tool does, though it does not explicitly distinguish itself from the closely related sibling tools get_supervisor and get_interviewer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus get_supervisor or get_interviewer, nor any mention of prerequisites or exclusions. The phrase 'by ID' implies the intended use case, but the agent is left to infer when the generic get_user is preferred over the role-specific siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It only says 'Compare response distributions', which weakly implies a read-only analysis, but it does not disclose that the tool flags percentage-point or z-score differences, excludes missing/threshold-failing groups, requires a Tabular export, or returns findings, recordsExcluded, and methodologyVersion. The schema's x_suso_qc metadata contains some of this, but the prose description itself does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with no filler besides a redundant tool-name prefix; the substantive clause is front-loaded. It is compact, but it sacrifices useful behavioral information, so the space is not used to maximum effect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters (0 required), nested objects, and no output schema, yet the description explains almost none of the invocation contract. The x_suso_qc block provides methodology and output shape, but the agent is left to infer how 'plan', 'rules', 'thresholds', and 'export_path' should be populated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, and the description adds a little meaning by suggesting that 'variables' will include grouping dimensions (interviewer, date, area, version) plus target variables. It does not help with the undocumented parameters ('plan', 'profile', 'confirm_plan_id', 'questionnaire_identity') or with the nested 'rules'/'thresholds' structure, so it only partially compensates for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Compare') and a concrete object ('response distributions'), and it names the comparison dimensions—interviewers, dates, areas, versions—so an agent can tell what the tool analyzes. It does not explicitly contrast it with the many sibling QC tools, and the leading 'qc_response_distribution_shift:' prefix merely repeats the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to choose this tool over the sibling QC tools or which input combination is required. The phrase 'across interviewers, dates, areas, or versions' only implies a use case; it does not state exclusions or alternatives, so an agent receives no selection help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden of behavioral disclosure. It mentions permission requirements and a confirmation parameter, but it does not describe whether the operation is destructive, reversible, or how unsupported cases are handled (beyond 'where supported'). The lack of return behavior or error conditions is a gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and follows with key requirements. It wastes no words and is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, output schema, or parameter explanations, the description is incomplete. It omits critical details about the profile parameter, return value, error conditions, and the exact meaning of 'where supported'. An agent would struggle to call this tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all parameters. It only hints at the confirmation parameter ('exact assignment confirmation') and implies assignment_id from context, but it completely fails to explain the 'profile' parameter. This is insufficient for a 3-parameter tool with no schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('set assignment size') and resource ('assignment'), with a clear scope ('to collected interviews where supported'). It distinguishes itself from sibling tools like change_assignment_quantity by specifying the intent to downsize, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions prerequisites ('Requires fieldwork_write/admin_write') and a constraint ('exact assignment confirmation'), implying when the tool is appropriate. However, it does not explicitly state when not to use it or mention alternative tools like change_assignment_quantity or assign_assignment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only hints at the potential absence of web mode state ('where available') but does not address error handling (e.g., assignment not found), whether the operation is read-only, or any permission requirements. The lack of explicit safety cues leaves the agent uncertain about 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that is front-loaded with the core purpose. Every word adds value: 'Get details for one Survey Solutions assignment' is efficient, and the 'web mode state' caveat is a brief but relevant extra. There is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters (one required), no output schema, and no annotations, the description is too sparse. It fails to explain the 'profile' parameter, the return structure, or any error conditions. The 'where available' clause is vague without context. An agent cannot confidently call this tool correctly based purely on the description and schema, especially given the zero coverage of parameter semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must explain the parameters. It only mentions 'assignment_id' implicitly via 'one assignment', but the 'profile' parameter (a string) is entirely unexplained. No format, meaning, or relationship to the assignment is provided, leaving the agent unable to correctly populate the request without external knowledge.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get'), a specific resource ('details for one assignment'), and the system ('Survey Solutions'). This distinguishes it from 'list_assignments' (which lists many) and 'get_assignment_history' (which gets history). The mention of 'web mode state where available' adds specific scope without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention that it is for retrieving a single assignment by ID, nor does it contrast with list_assignments or other assignment-related operations. The description merely states what it does, not the appropriate context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates a read-only operation, which is valuable. However, it does not disclose error behavior, permission implications, what exactly 'quantity/limit behavior' includes, or whether partial or empty settings are possible. The read-only nature is disclosed, but depth is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. It communicates the core action and target resource economically. Its brevity is a strength, though it may be too sparse to fully support tool selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, no annotations, and 0% parameter coverage, the description is not complete enough for an agent to confidently invoke it. The phrase 'quantity/limit behavior' remains ambiguous, and the purpose of the profile parameter is unexplained. More context is needed to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 for the undocumented parameters. It only hints at 'one assignment', loosely connecting to assignment_id, but says nothing about the optional profile parameter or its meaning. An agent cannot determine what profile does or how it affects the request.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and a specific resource ('quantity/limit behavior for one assignment'), making the tool's purpose clear. It is distinguishable from generic siblings like get_assignment or list_assignments because it focuses narrowly on quantity/limit settings. However, it does not explicitly differentiate itself from related tools such as change_assignment_quantity or downsize_assignment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. It does not mention that this read likely pairs with change_assignment_quantity, nor does it explain when get_assignment might be more appropriate. An agent must infer usage entirely from the name and input schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of conveying behavior. The word 'Get' suggests a read-only operation and 'status/details' indicates what is returned. However, it does not disclose behavior for missing jobs, expired exports, authentication needs, or whether the call has 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It leads with the verb and object, making it easy to scan, and every word contributes to the basic meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is too sparse to fully guide invocation. It does not explain what details are returned, how job_id is obtained, or what the optional profile parameter controls.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage and the description adds no meaning to job_id or profile. It does not even state that job_id identifies the export job or explain the role of the optional profile parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('status/details for a Survey Solutions export job'), making the tool's core purpose clear. It does not name or contrast sibling tools like list_export_jobs, so it lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus start_export, list_export_jobs, or cancel_export_job. The description implies a status-check workflow but never states prerequisites or the recommended call sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Read', which implies a non-mutating operation, but it does not disclose side effects, permissions, return format, or any other behavioral details. This is insufficient for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that is efficiently worded and front-loaded. It states the essential purpose without any wasted words, making it highly concise and appropriately structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low-complexity with one optional parameter and no output schema. The description states the purpose but does not indicate what the tool returns or any additional context. Since there is no output schema to compensate, a mention of the return value would improve completeness, but the simplicity of the tool makes a moderate score acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the 'profile' parameter at all. However, the input schema covers it 100% with a descriptive line, so the baseline is 3. The description adds no additional semantic meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the global notice setting with a specific verb and resource. It distinguishes from sibling set_global_notice and clear_global_notice via the verb 'Read', though it does not explicitly name them. This is clear but could be more explicit about the contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that it is for viewing the current notice, nor does it reference set_global_notice or clear_global_notice as alternatives for modification. There is no context about when it should or should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It says 'Get metadata' implying a read-only operation, but it does not explicitly state read-only, mention required permissions, error behavior for missing identities, or any side effects. The description is too skeletal to inform an agent about operational traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundancy. It states the action, resource, and identity format efficiently, which is ideal for a simple getter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the core action but misses key context: the profile parameter is unexplained, there is no mention of return value/failure behavior, and there is no differentiation from siblings. With no output schema and no annotations, these gaps make the definition incomplete for reliable agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: only questionnaire_identity is described (as 'GUID$Version format'), and profile is not. The description repeats the GUID$Version format but adds nothing new for questionnaire_identity, and completely omits any explanation of the profile parameter. It fails to compensate for the low schema coverage, leaving parameter meaning ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'metadata for one imported questionnaire/version', and the identity format 'GUID$Version'. It distinguishes from siblings like list_questionnaires (which lists all) and get_questionnaire_document (which retrieves the document). This is a specific and unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like list_questionnaires or get_questionnaire_document. It does not mention any conditions, prerequisites, or exclusions. An agent has no direct help in choosing this tool over its many questionnaire-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden. 'Retrieve' clearly signals a read-only operation, and the availability caveat about the active Headquarters build is useful. However, the description does not disclose what happens when the build does not expose the document, such as errors or fallback behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the action and resource. The conditional clause is a bit roundabout, but there is no redundant content or inflated length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, this description is incomplete. It does not specify what metadata is returned, how to handle the undocumented profile parameter, or what to do when the Headquarters build does not expose the document.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents questionnaire_identity with a GUID$Version format, but the profile parameter has no schema description and the tool description adds no parameter-level meaning. With 50% schema description coverage, the description should compensate for the undocumented 'profile' parameter but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Retrieve') and resource ('questionnaire document/design metadata'), so the core purpose is clear. However, it does not contrast this with sibling tools like get_questionnaire or compare_questionnaire_version_schemas, leaving some potential for confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool instead of alternatives. The phrase 'where the active Headquarters build exposes it' hints at a precondition, but it does not explain how to verify availability or which sibling tool to fall back on.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the tool is 'read-only', which is an important behavioral disclosure since no annotations are provided. However, it does not clarify what the evidence output looks like, whether any data is sensitive, or what limitations exist around 'available action logs'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that front-loads the read-only nature and names the key data sources. It is easy to parse and contains no filler, though it could have used the space to clarify parameters or output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description carries the full burden of explaining behavior, but it only says evidence is gathered. It does not describe return values, how the required issue_description is used, or what makes this distinct from other interviewer-focused tools. This is incomplete for a 5-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds little meaning to the parameters. 'Interviewer anomaly' hints at interviewer_id and issue_description, but from_utc, to_utc, and profile remain unexplained, leaving the agent without guidance on formats, optionality, or how they affect the investigation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Gather') and a clear object ('read-only evidence around an interviewer anomaly'), and names the data sources involved (interviews, assignments, action logs). This gives the tool a distinct investigative purpose, though it does not explicitly differentiate it from sibling tools like get_interviewer_actions_log or summarize_interviewer_activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to choose this tool over alternatives. The phrase 'around an interviewer anomaly' implies a use case, but it does not state when not to use it or point to any sibling tool that might be more appropriate for narrower questions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only restates the action and scope; it does not say what 'options' contains (IDs, titles, versions?), whether results depend on the configured profile, whether the operation is read-only, or how empty results behave. The verb 'List' implies non-destructive, but nothing confirms it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 11-word sentence that is front-loaded with the verb and contains no filler or repetition of structured data. Structurally efficient for a tool of this simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity (one optional parameter), the description is incomplete for the confusing sibling context. With zero annotations and no output schema, an agent needs at least a hint about what the returned 'options' look like and how this differs from list_statistics_questions / list_questionnaires; neither is addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the single optional 'profile' parameter is already documented as 'Optional configured Survey Solutions profile name.' The description adds no parameter-level detail, which is acceptable at the baseline 3 since the schema fully carries the weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('questionnaire options'), scoped by 'available to Survey Solutions statistics reporting,' which implicitly distinguishes it from the plain list_questionnaires sibling. However, the distinction is implicit rather than explicit, and it does nothing to disambiguate from the similarly named list_statistics_questions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no when-to-use guidance, no exclusions, and names no alternatives. In a sibling set containing list_questionnaires, list_statistics_questions, and get_statistics_report, an agent receives no help choosing among them based on this description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure, but it only restates the basic operation. It does not describe pagination behavior, response shape, permissions, or server quirks; the offset normalization detail is relegated to the schema rather than the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler or redundant phrasing. It is appropriately concise for a simple list operation, though it is terse enough that it omits useful context covered under other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description is incomplete for an agent to call the tool confidently. It does not explain what the returned interviewer objects contain, how pagination works, how the query object merges with limit/offset, or what profile is expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60%, and the description itself provides no direct parameter documentation. However, the phrase 'assigned to a supervisor' does clarify the required supervisor_id meaning. The optional profile and query parameters remain unexplained by the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('List') and a specific resource ('interviewers assigned to a supervisor'), making the core operation clear. It is broadly distinguishable from siblings like list_supervisors or get_interviewer, but it does not explicitly contrast with them or mention scope exclusions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given for when to use this tool versus alternatives such as list_interviews, list_supervisors, or get_interviewer. There is also no mention of prerequisites like needing a valid supervisor_id or an active profile.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure, but it only states the core function. It does not mention how findings are reported (e.g., output format), edge cases such as rejection or handling of missing coordinates, or any side effects. The schema's x_suso_qc exclusion rules and output contract are part of the schema, not the description, so they don't count toward transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that gets to the point immediately. It is efficient and readable, though it redundantly includes the tool name as a prefix. Despite the slight redundancy, it conveys the purpose without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, nested objects, no formal output schema), the description is far too minimal. It does not explain the expected output structure, requirements like export type, or how the flagging results are delivered. The schema provides some context, but the description itself leaves an agent without enough information to confidently invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, with several parameters (plan, profile, confirm_plan_id, questionnaire_identity) lacking descriptions. The tool description adds no parameter-level detail beyond what the schema already provides. It does not clarify how rules, thresholds, or variables should be structured beyond the existing schema text, leaving a significant gap in compensating for the uncovered parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Flag') and the subject ('low GPS accuracy or coordinates outside expected areas'). It effectively distinguishes this QC tool from siblings like qc_gps_duplicates_and_clusters by focusing specifically on accuracy and area rules, even without explicitly naming alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus other QC tools (e.g., qc_gps_duplicates_and_clusters). The description implies the use case but does not state conditions, prerequisites, or exclusions. An agent would have to infer when this tool is appropriate without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only states the core flagging behavior. It does not mention how findings are returned, whether the tool is read-only, threshold default behavior, or exclusions such as missing/categorical values; the schema metadata provides some of this, but the description itself does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
At one sentence, the description is compact and front-loads the purpose. The repeated tool-name prefix is minor redundancy, but there is no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has eight parameters, no output schema, and many QC siblings, yet the description omits input requirements, return shape, and required export type. Although x_suso_qc metadata contains an output contract and methodology summary, the free-text description alone is not enough for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: variables, thresholds, and export_path have inline descriptions, while plan, rules, profile, confirm_plan_id, and questionnaire_identity are undocumented. The description adds no parameter-level meaning, so it does not compensate for the undocumented half; an agent cannot tell what plan, rules, profile, or confirm_plan_id mean from either source.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Flag') and a precise resource ('numeric heaping'), with concrete examples ('excessive 0/5/10 endings'). This makes it distinguishable from sibling QC tools like qc_straightlining or qc_duplicate_records 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to prefer this tool over alternatives, e.g., when variables are continuous/numeric and suspected of rounding. The examples imply use for round-number detection, but there is no exclusion guidance or relationship to sibling QC checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. 'Compare' implies a read-only analysis, but the description does not explicitly say whether data is modified, what gets flagged, how thresholds behave, or what side effects might occur. It does not disclose the output contract or exclusion behavior that an agent would need to anticipate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose in a single sentence. The tool name is repeated before the colon, slightly reducing efficiency, but there is no redundant or irrelevant content. It earns its place but could be more informative without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—8 parameters, nested objects, no output schema, and no annotations—the one-sentence description is not enough for an agent to invoke it confidently. It lacks guidance on required inputs, threshold semantics, expected findings, and how this QC check differs from related tools. The schema provides some structured hints, but the description alone leaves major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, and the description adds no parameter-level meaning. It does not explain how variables, thresholds, export_path, or the nested plan/rules objects should be provided. The schema documents some parameters, but the description fails to compensate for the undocumented ones.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific analysis: comparing missing/nonresponse rates across interviewers. It uses a concrete verb ('compare') and a specific resource/dimension ('across interviewers'), which distinguishes it from sibling QC tools like qc_targeted_missingness. Even without naming alternatives directly, the interviewer-level focus makes its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool instead of other QC or missingness-focused tools. It does not mention when not to use it, nor does it reference alternatives. The schema adds methodological context but no explicit usage or exclusion rules beyond data requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no output schema, the one-line description must carry the behavioral disclosure burden but only states the flagging action. It does not disclose side effects, output behavior, read-only status, or required inputs beyond variables, so an agent has limited understanding of what happens when the tool is invoked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler, making it quick to parse. The repeated tool name prefix is mildly redundant, and the brevity leaves substantial context to the schema, but the structure itself is clean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no annotations and no output schema, a one-line description is not complete enough. The x_suso_qc metadata supplies some requirements and output contract, but the description does not help an agent decide how to populate plan, rules, thresholds, or export_path, nor does it navigate the large sibling QC toolset.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, and the description adds little meaning for the undocumented parameters such as plan, rules, profile, confirm_plan_id, and questionnaire_identity. It merely reinforces the variable-type constraint already present in the schema metadata and does not compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (Flag) and a precise resource (repeated identical answers across selected ordinal/categorical variables), which clearly identifies the straightlining concept. This also differentiates it from siblings like qc_logical_consistency and qc_response_distribution_shift without requiring schema inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for detecting straightlining but gives no explicit guidance on when to prefer it over other QC siblings. It does not mention alternatives, exclusions, or when not to use it; supporting constraints like minimum data and supported variable types live only in schema metadata.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden, but it only says 'Flag suspicious bursts' without explaining the methodology, what counts as suspicious, whether it is read-only, or what it returns. The schema's x_suso_qc outputContract adds some structure, but the description itself remains thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no obvious padding. The redundant tool-name prefix is minor. It is front-loaded and easy to parse, though very brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters, nested objects, no output schema, and no annotations, yet the description does not explain inputs, configuration, or expected outputs. The x_suso_qc extension fills some gaps, but an agent would still lack practical guidance on how to invoke and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%, and the description adds no parameter-level meaning. It does not explain plan, rules, profile, confirm_plan_id, questionnaire_identity, or how thresholds map to the detection behavior. The schema's own descriptions for thresholds and export_path carry most of the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Flag') and resource ('submissions'), and identifies the behavior: flagging suspicious bursts or very short gaps between submissions. This clearly differentiates it from sibling QC tools like qc_duplicate_records or qc_interview_duration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as investigate_interviewer_anomaly, summarize_interviewer_activity, or other QC checkers. The schema mentions required export type and minimum data, but the description itself provides no usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does disclose important behavioral constraints: permission requirements and the need for exact interview confirmation. However, it does not describe side effects, return behavior, or the optional rejection-workflow semantics hinted at by the responsible_id parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, with the purpose front-loaded and the key requirements in the second sentence. There is no filler or redundant content; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is too thin. It leaves comment and profile unexplained, does not clarify the optional responsible_id/rejection workflow, and gives no indication of success or error behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, and the description adds only minimal meaning beyond the schema: 'another responsible user' and 'exact interview confirmation.' It does not explain the comment or profile parameters, and the phrasing conflicts somewhat with responsible_id being optional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Reassign'), a clear resource ('an interview'), and the target ('another responsible user'). It is clear and distinct enough to identify the operation, though it does not explicitly differentiate itself from similar siblings like assign_interview_supervisor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions required permissions and exact interview confirmation, but it gives no guidance on when to prefer this tool over siblings such as assign_interview_supervisor or assign_assignment. No alternatives, exclusions, or workflow conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does disclose permission requirements and hints at a confirmation safeguard, which suggests the operation is consequential. However, it does not explain side effects, reversibility, or what happens to associated interviews, leaving significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. It states the action first, then the requirements, making it easy to parse at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a mutation with no annotations, no output schema, and four parameters at 0% schema coverage. The description is too terse to cover what quantity means, how confirmation works, expected effects, or return values. More context is needed for an agent to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 semantics. It only hints at confirm_assignment_id via 'exact assignment confirmation' and leaves quantity, assignment_id, and profile unexplained. The term 'quantity' is somewhat self-explanatory, but the confirmation parameter's exact requirement (e.g., must match assignment_id) is not stated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Change') and resource ('assignment quantity'), making the core purpose clear. However, it does not explicitly differentiate from sibling tools like 'downsize_assignment' or 'change_assignment_status', though the quantity focus offers some inherent distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a prerequisite ('Requires fieldwork_write/admin_write') and a safety instruction ('exact assignment confirmation'), but no guidance on when to choose this tool over related alternatives such as downsize_assignment or change_assignment_target_area. There is no mention of scenario, exclusions, or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does disclose that the operation requires fieldwork_write/admin_write permissions and exact assignment confirmation, which are meaningful safety-related behaviors. However, it does not describe side effects, reversibility, validation behavior, or what happens upon success or failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. The core action comes first, followed by the most important safety and permission constraints. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a mutation operation with no annotations, no output schema, and no parameter descriptions, yet the description provides only the action, a permission requirement, and a confirmation requirement. It omits valid target_area values, behavior for mismatched confirmation IDs, effect on existing assignment state, and return/error semantics. This is not enough for an agent to call it reliably in all cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 for the four undocumented parameters. It adds some meaning to confirm_assignment_id via 'exact assignment confirmation' and implicitly clarifies target_area, but it leaves assignment_id and especially profile unexplained. This is only partial compensation for the complete lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Change assignment target area.' It is clear and accurately reflects the tool's operation, and the target-area focus helps differentiate it from sibling assignment tools. However, it does not explicitly differentiate from related tools such as change_assignment_quantity or change_assignment_status, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like change_assignment_quantity or change_assignment_status. The description only mentions permissions and exact assignment confirmation, which are prerequisites rather than usage context. An agent would have to infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It usefully discloses the permission requirement and the special web_mode/quantity -1 behavior. However, it does not describe output behavior, side effects, or consequences of unspecified parameters, which matters for a creation operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences with no filler. The primary action comes first, followed by the special capability and permission requirement, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex 12-parameter tool with no annotations and no output schema, yet the description provides only minimal context. It leaves many optional parameters, expected behavior, and alternatives unexplained, so an agent cannot safely infer full usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, so the description must compensate. It adds meaning for web_mode and quantity by explaining the open-web-link use case, but 12 parameters exist and most remain unexplained in both schema and description. This is partial compensation at best.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a Survey Solutions assignment, naming a specific verb and resource. It also highlights the special open-web-link capability, which helps define the tool's scope. However, it does not explicitly distinguish this tool from the sibling create_external_test_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as create_external_test_link or other assignment-related tools. It mentions required permissions, which is contextual, but not when to choose or avoid this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does reveal that the tool starts exports and returns combine guidance rather than combined files, but it omits important behaviors such as whether exports run asynchronously, whether export jobs are created and tracked, what side effects occur, and whether permissions or profile context are required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence with no filler, front-loading the primary action and resource before the secondary outcome. It earns its place by communicating both the side effect and the return value in minimal words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has six parameters, no parameter descriptions, no output schema, and no annotations, yet the description only captures the general workflow. An agent would not know how to choose between export_type and export_types, what interview_status options are valid, how output_dir is used, or what 'version-aware combine guidance' actually includes, so the description is not complete enough for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not compensate by explaining the parameters. 'One or more formats' loosely maps to export_type/export_types, and 'all questionnaire versions' maps to questionnaire_id_or_title, but profile, output_dir, and interview_status are left entirely unexplained despite having no schema-level descriptions or enums.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Start exports'), a clear resource ('all questionnaire versions'), and a distinctive outcome ('return version-aware combine guidance'). It clearly implies a combined export-and-combine workflow, but it does not explicitly differentiate itself from the sibling tools with very similar names such as export_and_combine_questionnaire_versions or combine_versioned_exports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'all questionnaire versions in one or more formats' implies the intended use case: when an agent needs the full multi-version, multi-format export workflow. However, it gives no explicit guidance on when to prefer this tool over sibling tools like export_all_formats, export_all_questionnaire_versions, or combine_versioned_exports, and no stated exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose a useful behavioral detail: staleness is computed using 'available updated/history timestamps.' However, it does not state whether the operation is read-only, what the output shape is, or how status/profile affect the search.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. The core purpose and key threshold are front-loaded, and every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has four parameters, no annotations, and no output schema, yet the description only addresses min_days. It lacks information about how status, now_utc, and profile interact, what 'no movement' means precisely, and what the tool returns. This is not complete enough for reliable autonomous invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 explains min_days as the staleness threshold, but leaves status, now_utc, and profile semantically unexplained. This is insufficient for an agent to confidently set those parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it finds interviews with no movement for at least min_days. This makes the core purpose understandable and distinguishes it from a plain list_interviews tool, though it does not explicitly name or contrast sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives such as list_interviews, get_interview_history, or investigate_interviewer_anomaly. The description implies its use case but provides no explicit context, exclusions, or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description itself must establish the operation. The 'Get' verb implies read-only behavior, and the list of statistics communicates what the caller will receive. It does not disclose output shape, permissions, or error behavior, but for a retrieval tool this is acceptable baseline transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single direct sentence front-loads the action and resource, then lists the returned statistics. No filler words or repetition; the enumerative list is a bit long but each item earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter retrieval tool, the description covers the main output fields and enough context to call with interview_id. However, with no output schema, no annotations, and undocumented 'profile', the definition leaves some agent uncertainty about return structure and how the optional parameter affects the call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain either parameter. 'interview_id' is inferable from 'interview-level', but the optional 'profile' parameter is never mentioned, and no format or value guidance is given. The description adds no parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a clear verb-resource pair: 'Get interview-level statistics' and enumerates specific fields (answered/not answered, valid/invalid, comments count, duration, key, status, web interview URL). It does not name or contrast with sibling tools like get_interview_details or get_statistics_report, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to choose this tool over alternatives, nor any exclusions. The word 'interview-level' hints at scope, but the description never says 'use this for per-interview stats; use get_statistics_report for aggregates' or similar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. The verb 'Check' implies a read-only, diagnostic operation rather than a mutation, which is credible given the qc_* naming convention. However, it does not explicitly confirm no side effects, nor does it disclose behaviors like excluding rows with missing parent keys or requiring a Tabular export beyond what appears in the schema metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted exposition. The redundant 'qc_roster_consistency:' prefix is minor, and the sentence conveys the essential topic efficiently without being padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema's x_suso_qc metadata supplies useful structured context: output contract, methodology summary, required export type, supported variable types, and minimum data requirements. Still, the description itself does not tie these together or clarify when to choose this tool over qc_logical_consistency, and the lack of required parameters plus no output schema leaves meaningful ambiguity for an agent deciding how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 8 parameters and only 50% schema description coverage, the description should compensate by explaining how parameters relate, but it only names the high-level concepts 'roster counts' and 'nested roster relationships'. It gives no guidance on populating `rules`, `thresholds`, `plan`, `export_path`, or `variables` beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Check') and a concrete resource ('roster counts and nested roster relationships'), so an agent can tell it is a roster-focused QC tool. It is not a pure tautology, and the roster focus differentiates it broadly from sibling tools like qc_logical_consistency. However, 'internal consistency' is somewhat vague about exactly which comparisons are made.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the many sibling QC tools, nor any mention of prerequisites, exclusions, or when not to use it. The intended use must be inferred entirely from the word 'roster' in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does disclose two important behaviors: it requires admin_write permission and requires exact questionnaire identity confirmation, which conveys a safety check. However, it does not describe side effects, reversibility, or failure behavior, leaving meaningful gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The core action is front-loaded, and the permission and confirmation requirements are stated succinctly. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a permission-sensitive write operation with no annotations and no output schema, the description is incomplete. It does not explain what criticality_level values are valid, what happens on identity mismatch, whether the operation is reversible, or what the response looks like. An agent could pass an invalid value or misunderstand the outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, covering questionnaire_identity and confirm_questionnaire_identity, but criticality_level and profile lack descriptions. The description adds no parameter-level meaning, such as acceptable criticality values or what profile does, so the agent is left to infer those semantics from the parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Set') and the resource ('questionnaire criticality settings') with enough specificity to distinguish it from the sibling get_questionnaire_criticality_level. It is not as precise as it could be about what 'criticality settings' includes, but the core purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides conditions for using the tool ('Requires admin_write permission') but gives no guidance on when to use it relative to alternatives such as get_questionnaire_criticality_level, or when it should not be used. No when-to-use or when-not-to-use context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden of behavioral disclosure. It mentions the permission requirement but does not explain what archiving does to the user's data, assignments, or access, nor whether the action is reversible or has side effects. This is insufficient for a mutating administrative action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: one sentence states the action and scope, and a second states the permission requirement. Every word contributes, and the core purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and minimal parameter documentation, the description does not provide enough context. It omits the meaning of confirm_user_id, the effect of archiving, reversibility, and what response or outcome to expect. The permission note helps but is not sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no explanation of the three parameters. While user_id is somewhat self-explanatory, confirm_user_id and especially profile are left undefined; confirm_user_id likely serves as a safety confirmation but this is never stated. The description fails to compensate for the lack of schema-level parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Archive'), identifies the resource ('user'), and narrows the scope to 'a supervisor or interviewer user,' which helps distinguish it from related sibling tools like unarchive_user or create_user. This is clear and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite ('Requires admin_write permission') and implies the target audience, but it does not explicitly state when to use this tool versus alternatives such as unarchive_user, nor does it mention any exclusion conditions. Usage context is implied rather than fully specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It explicitly states that the operation changes server job state and requires specific permissions, which is valuable side-effect information. However, it does not explain whether cancellation is reversible, what happens if the job is already completed, or what response/error behavior to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It front-loads the core action ('Cancel an export job') and then provides a concise behavioral/permission caveat. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three parameters, no output schema, no annotations, and no schema-level descriptions. The description covers purpose and permission but omits critical operational details, especially the meaning of confirm_job_id and the behavior of canceling jobs in different states. An agent would likely need additional information to call this tool confidently and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of any parameter. In particular, the required confirm_job_id parameter is non-obvious and not described; an agent cannot infer its purpose, format, or relationship to job_id. The description adds no parameter-level meaning beyond the schema's bare type/required declarations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Cancel an export job,' which clearly identifies the action and target. It also notes the permission requirement and the fact that it changes server-side state, which helps distinguish it from read-only export tools like get_export_job and list_export_jobs, though it does not explicitly name any sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when an export job needs to be canceled. It adds the prerequisite that fieldwork_write or admin_write permission is required, which is useful usage context. However, it does not provide explicit guidance about when not to use it or how it compares to alternatives such as waiting for, restarting, or re-exporting a job.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It does convey that this is an informational/read-style tool returning content (explanations, risk warnings), but it never explicitly states safety traits such as being a non-mutating operation, or what happens on failure. The 'risk warnings' mention adds modest value beyond a bare one-liner.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with no filler or redundancy. It front-loads the core purpose and packs the risk-warning behavior into the same breath. Slightly more structure (e.g., flagging it as read-only) would raise it further.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple informational tool with two optional boolean parameters and no output schema, the description captures the essentials: what it returns and its content scope. It does not describe return structure, but given the tool's low complexity, this gap is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 both boolean parameters. It touches on 'risk warnings', which maps to include_risks, but never explains include_examples — the examples dimension is entirely absent. One of two parameters is unaddressed, and neither parameter's effect on output shape is clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('Return human-readable explanations of MCP permission modes') and indicates the content scope (what each allows/blocks, risk warnings). It is clear enough to distinguish from siblings like recommend_permission_mode or get_profile_permissions, though it never names them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance is given. The description does not mention alternatives such as recommend_permission_mode or explain_blocked_tool, nor when an agent should choose this over them. There are no exclusions or routing hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It adds a meaningful behavior detail by noting that it uses /swagger/v1/swagger.json when available, but it does not disclose what happens when that endpoint is unavailable, whether results are cached, or how the 'refresh' parameter affects behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is one focused sentence with no wasted words. The main purpose is front-loaded and the swagger.json detail is directly relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, no annotations, and zero parameter documentation in the schema, so the description must carry most of the burden. It gives the general purpose but omits parameter semantics, fallback behavior when swagger.json is unavailable, and what the returned capabilities look like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
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 by explaining parameters such as 'profile' and 'refresh'. It does not mention either parameter, leaving their meaning entirely to the schema's bare names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Inspect') and names a clear resource ('REST/GraphQL capabilities for the Survey Solutions server'). It does not explicitly distinguish itself from sibling tools like rest_request or openapi_operation, but the inspect/discover intent is apparent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The verb 'Inspect' implies this is for discovering what API operations are available, and the mention of swagger.json gives a concrete mechanism. However, it does not explicitly state when to use this over rest_request, openapi_operation, or graphql_query, nor does it provide any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, but it only says 'list active supervisors' and does not disclose important behaviors such as pagination, sorting, response shape, or how 'active' is determined. The presence of limit/offset/query parameters in the schema hints at paging behavior, but the description itself adds little beyond the basic list semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that leads with the action and resource, containing no filler words. It is appropriately concise for a simple listing tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters, a nested 'query' object, and no output schema, the one-sentence description is too thin. It does not explain pagination behavior, the meaning of 'active', the role of 'profile', or what the response contains, so an agent would need to infer or probe to use it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no meaning to the parameters; limit, offset, and query are already documented in the schema, so no extra value is provided there. However, the 'profile' parameter lacks a schema description and is also ignored in the tool description, leaving one parameter semantically ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clear resource ('active supervisors in the workspace'), making the tool's function immediately understandable. It also differentiates from sibling tools like 'list_supervisor_interviewers' and 'get_supervisor' because it targets supervisors themselves, not their interviewers or a single supervisor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as 'list_supervisor_interviewers' or 'get_supervisor'. The description states only what the tool does and gives no exclusions, prerequisites, or decision context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It only states the core flagging action and data sources; it does not disclose that this is an analysis-only operation, how thresholds are applied, whether data is mutated, or what the caller receives. Richer methodology details exist in the x_suso_qc metadata, but not in the description itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler and integrates the key data-source distinction efficiently. It is appropriately brief, though it could have front-loaded what the caller gets back.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters, several undocumented, no output schema, and no annotations. The one-sentence description does not cover thresholds, required export setup, profile/plan configuration, or result shape, leaving an agent with insufficient context to invoke the tool robustly despite the extra x_suso_qc metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, so the schema partially documents parameters like variables, thresholds, and export_path. The description adds useful context by clarifying that duration data can come from Tabular fields or Paradata duration events, which maps to the required export type, but it does not explain several undocumented parameters such as plan, profile, confirm_plan_id, or questionnaire_identity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Flag'), a precise object ('unusually short or long interviews'), and the two data sources ('duration fields from Tabular data or duration events from Paradata'). This clearly distinguishes it from sibling QC tools such as qc_submission_timing_bursts or qc_straightlining.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives, nor are any exclusions or prerequisites mentioned. The intended context is implied by the 'qc_' naming convention and the description's flagging language, but no explicit when-to-use or when-not-to-use information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden, but it only says rules are applied. It does not disclose that failing records are reported, that structurally inapplicable rows may be excluded, or what the output counts and findings contain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one compact sentence and front-loads the action. The only structural redundancy is the 'qc_logical_consistency:' prefix, which repeats the tool name, but there is no padding or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with eight parameters, nested objects, no required parameters, and no output schema, a one-sentence description is insufficient. The x_suso_qc schema metadata partially compensates with output contract and minimum data requirements, but key invocation details remain ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, so the schema itself documents rules, variables, thresholds, and export_path. The description adds no parameter-level meaning beyond mentioning variables, leaving plan, profile, confirm_plan_id, and questionnaire_identity without any documented semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Apply') and resource ('user-supplied logical rules') plus the scope 'across variables,' which helps distinguish it from the many built-in QC sibling tools. It is clear but does not explicitly contrast it with alternatives such as qc_roster_consistency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: an agent should invoke this when the task involves applying user-supplied logical rules to variables. It provides no explicit when-to-use/when-not-to-use guidance, prerequisites, or alternative tool routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It discloses the permission requirement but does not explain what unarchiving changes, whether it is reversible, or what happens if the assignment is already active. This is thin for a mutation operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with the core action front-loaded and the permission note second. There is no filler or repeated information, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and zero parameter coverage, the description is too sparse. An agent can infer the basic action but lacks enough context about parameters, effects, and expected behavior to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description is silent about both parameters. The agent cannot learn from the description what 'assignment_id' refers to or what role the optional 'profile' parameter plays, so the description fails to compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Unarchive an assignment.' This clearly distinguishes it from sibling tools like archive_assignment and unarchive_user, leaving no ambiguity about what operation is performed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The permission prerequisite gives some context, but the description does not explicitly state when to use this tool versus alternatives such as archive_assignment or unarchive_user. The intended use is implied by the name and verb rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosure. It does add behavioral context by requiring fieldwork_write/admin_write and exact interview confirmation, which signals a mutating, safety-sensitive operation. However, it does not disclose side effects, reversibility, failure behavior, or what happens to the existing assignment/supervisor relationship.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that packs action, conditional support, permission requirements, and safety confirmation with no repetition of the tool name or schema. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with no output schema, no annotations, and five parameters, the description is too thin. It does not explain several parameters, return behavior, side effects, or how the agent should distinguish this from assign_interview and other supervisor/interview tools. The available schema descriptions only partially fill the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, and the description does not compensate. It references 'exact interview confirmation' aligning with confirm_interview_id, but it adds no meaning for comment, profile, interview_id, or responsible_id beyond what the schema already states. The schema itself covers responsible_id and confirm_interview_id, leaving other parameters under-explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Reassign' with a clear resource 'interview' and adds the qualifier 'at supervisor level', which helps distinguish it from the generic assign_interview sibling. However, it does not explicitly name or contrast the sibling tool, so it falls just short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context: this is a supervisor-level reassignment supported only by the active Headquarters build, and it states required permissions. It does not explicitly say when to prefer this tool over assign_interview or other assignment-related tools, nor does it state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose a key behavioral trait: 'read-only fieldwork status' implies the tool does not mutate data, which is helpful. However, it does not mention any other behaviors such as output format, side effects, or whether permissions are required. The safety hint earns a baseline score but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the purpose and includes the important read-only qualifier. Every word contributes meaning; there is no redundancy or filler. It is appropriately concise for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description is incomplete for correct selection among many similar sibling tools. It does not explain what a 'fieldwork brief' contains, how it differs from other summaries, or what the output will look like (no output schema). The agent has insufficient context to choose this tool over summarize_fieldwork_status or other related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the single optional parameter 'profile' is fully described in the schema as 'Optional configured Survey Solutions profile name.' The description adds no additional parameter meaning. With full schema coverage, the baseline is 3, and the description does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Generate a compact fieldwork brief from current read-only fieldwork status.' It clearly indicates the tool produces a brief from status, which is a distinct purpose. However, it does not differentiate from sibling tools like summarize_fieldwork_status or summarize_interviewer_activity, which also deal with fieldwork summaries, so it lacks explicit sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. With many sibling tools that summarize fieldwork status, the agent receives no explicit condition or exclusion to select this tool over summarize_fieldwork_status. Usage is only implied by the name and description, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It usefully lists what the catalog contains and the OpenAPI availability condition, but it does not disclose whether refresh_capabilities causes side effects, whether network calls are made, or how availability is determined.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. It states the primary purpose first and then compacts the distinguishing metadata fields and caveat into a readable, efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with seven parameters, no output schema, and no annotations, this description is incomplete. It omits semantics for profile, refresh_capabilities, and include_server_availability, and does not explain the return shape or how filters combine, leaving significant gaps for an agent deciding how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents category, permission, side_effect, and availability, while profile, refresh_capabilities, and include_server_availability remain undocumented. The description adds context by naming output fields that map to permission, side effect, and availability, but it does not explain the boolean parameters or the profile parameter, so it only partially compensates for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: it returns an agent-facing catalog of all MCP tools, and lists specific metadata fields. It does not explicitly differentiate from related introspection tools like get_api_capabilities, but its scope is specific enough to be understood.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no exclusions, and no mention of related tools. The only conditional phrase, 'when OpenAPI is available,' describes behavior rather than usage context, so an agent is left to infer when this catalog should be consulted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It does disclose the permission requirement for mutations and distinguishes read-only queries, which is useful. Still, it omits details about error behavior, response format, or side-effect consequences beyond the word 'mutations.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single concise sentence that front-loads the tool's purpose and adds a critical permission caveat. There is no filler, redundancy, or repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a raw GraphQL tool with no annotations, no output schema, and undocumented parameters, this description is too sparse for safe invocation. It explains what the tool does and the permission gate for mutations, but leaves parameter semantics, usage context, and operational details unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the three parameters: query, profile, and variables. The word 'GraphQL query' may imply what the query parameter holds, but profile and variables are completely undocumented, leaving a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Run a Survey Solutions GraphQL query.' It clearly identifies this as a GraphQL tool, which separates it from REST or OpenAPI siblings, though it does not explicitly compare against those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context that read-only queries are generally allowed while mutations require raw_api permission and allowRawGraphqlMutations. However, it does not explicitly say when to prefer this tool over sibling tools like rest_request or openapi_operation, nor does it describe when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description frames the tool as an analytical comparison rather than a mutation, which gives some behavioral signal in the absence of annotations. However, it does not state the before/after export dependency, exclusion behavior, or output shape in the tool description itself; those live only in x_suso_qc metadata/input schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The text is one focused sentence with no filler, and the main verb and target are front-loaded. The 'qc_intervention_followup:' prefix repeats the tool name, which is the only minor inefficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The input schema is relatively rich (x_suso_qc provides outputContract, exclusionRules, required export type, and minimum data requirements), so the sparse description is partially supported. Still, with eight parameters, no output schema, and no usage guidance among many similar QC tools, the overall definition is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 50% schema coverage and no parameter explanations in the description, the agent is left to infer what 'plan', 'confirm_plan_id', 'questionnaire_identity', and 'profile' mean. The phrase 'targeted interviewers, variables, or cases' loosely maps to the variables parameter, but it does not compensate for the undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('compare'), a clear resource ('post-feedback outcomes'), and the target axes ('targeted interviewers, variables, or cases'), so an agent can tell what the tool does. It does not explicitly contrast itself with nearby qc_* siblings, and the top-level wording leaves the before/after baseline implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Post-feedback' and 'targeted' imply after an intervention has been delivered, which is useful usage context. There is no explicit when-to-use/when-not-to-use guidance or mention of alternatives among the many sibling QC tools, so the guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It communicates that the tool produces a least-permissive recommendation without mutating anything, which is useful, but it does not explain how the recommendation is determined, whether profile context influences it, or what the returned artifact looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with concrete examples and no redundancy. Every word contributes to clarifying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description leaves important context uncovered: the meaning of 'profile', the shape of the recommendation, and how this tool relates to permission-related siblings. It is adequate for identifying the tool but not for confidently using it across contexts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 for both parameters. It clearly maps to task_description through 'described task' and examples, but the optional 'profile' parameter is never mentioned or explained. This leaves part of the input contract undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Recommend the least-permissive permission mode') and a clear resource/input ('for a described task'), with concrete examples such as 'export data' and 'reject interviews'. It is unambiguous about the tool's function, though it does not explicitly differentiate from sibling tools like describe_permission_modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'for a described task' phrasing and the 'e.g.' examples imply when the tool should be used. However, it does not explicitly compare against alternatives such as describe_permission_modes or generate_permission_change_command, so the routing guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It usefully notes that GET is allowed by default and writes/deletes require explicit raw permission flags, but it does not mention possible side effects, error behavior, request limits, or what happens when the raw API is disabled or permissions are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact sentences with no filler. The core purpose is front-loaded and the permission guidance earns its place, making this an appropriately sized and well-structured definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a powerful arbitrary-endpoint tool with 5 parameters, no output schema, no annotations, and low schema coverage, yet the description provides no examples, no return/error behavior, and no explanation of the ambiguous parameters. The existing text is a starting point but is far from complete guidance for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 20%, with only 'path' described in the schema, and the description adds no parameter-level detail. The semantics of 'profile', 'body', and 'query' remain unexplained, and 'profile' in particular is ambiguous despite being a required context for some API calls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the tool as a 'raw REST escape hatch', which signals a generic HTTP request capability and distinguishes it from the many specialized siblings. However, it never explicitly states the operation as 'make an arbitrary Survey Solutions API request', so some inference from the name and schema is required.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'escape hatch' implies this tool is for cases not covered by dedicated tools, but there is no explicit 'use this only when no specialized tool exists' guidance. It also does not explain when GET vs write methods should be used beyond permission hints, leaving the agent to infer route selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral transparency burden. It discloses the required permission (admin_write) and the mutating nature of the operation, but it does not mention whether calling it overwrites an existing notice, whether the operation is reversible, or what the response or side effects are.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core action and includes the key permission requirement. It is concise, but the extreme brevity leaves out parameter and usage details that would make it more useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters, no output schema, and no annotations, the description is under-specified. It does not explain the format or constraints of 'message', the meaning or possible values of 'profile', whether the global notice replaces any previous notice, or what the tool returns. Sibling tools are present but not referenced for disambiguation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about either parameter. The required 'message' parameter is only generically understandable from its name, and 'profile' is completely unexplained. With no parameter documentation in the schema or description, an agent cannot reliably fill in these fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Set') and resource ('Survey Solutions Headquarters global notice'), and this operation is semantically distinct from sibling tools like get_global_notice and clear_global_notice. The resource is named precisely enough for an agent to understand what is affected.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The permission requirement ('Requires admin_write permission') gives some context, but the description does not explicitly state when to use this tool versus the related get_global_notice or clear_global_notice tools. Usage is implied by the verb 'Set', but no alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'read-only', which is an important behavioral safety signal, and 'high-level' indicates an aggregated view rather than raw data. However, with no annotations present, the description carries the full burden and does not disclose output format, aggregation logic, or profile dependency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one tight sentence with no filler. It front-loads the operation type and scope, making it immediately scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, a broad summary tool covering four entity types needs more detail about what the returned summary contains, what 'status' means, and whether the optional profile changes the scope. The description is too thin for an agent to confidently anticipate the tool's output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single 'profile' parameter is already self-explanatory from the schema. The description adds no additional meaning about how the profile affects the summary, so it sits at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation (summarize), a distinguishing scope (fieldwork), and enumerates the entities covered: questionnaires, assignments, interviews, and users. It clearly distinguishes itself from more targeted sibling summaries like summarize_interviewer_activity, though 'status' remains somewhat general.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to choose this tool over alternatives, nor any mention of exclusions or complementary tools. The word 'high-level' hints at an overview use case, but no concrete selection criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It does disclose that the tool may activate web mode and creates an unlimited web assignment, which are meaningful side effects. However, it omits important behavioral context such as authorization requirements, reversibility, idempotency, and what happens if web mode is already active.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with a colon and one clarifying clause. It front-loads the core purpose and contains zero filler words while conveying two key behaviors.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five parameters, 0% schema coverage, no annotations, and no output schema, the description is too sparse to support correct invocation. Required fields like questionnaire_identity and responsible are not semantically defined, optional fields like identifying_data are opaque, and there is no indication of what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain any of the five parameters. The agent gets no guidance on what questionnaire_identity, responsible, identifying_data, profile, or comments mean or how to format them. The phrase 'unlimited web assignment' is about the outcome, not parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' with the resource 'external web-interview test link' and further specifies the action as 'activate web mode if needed and create an unlimited web assignment.' This clearly distinguishes it from related siblings like activate_web_interview and create_assignment by describing a composite action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool by saying 'activate web mode if needed,' but it never explicitly states when to prefer this over the sibling tools activate_web_interview or create_assignment. There are no alternatives, exclusions, or conditions provided, so usage guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It does reveal that a file is written to a local host path, but it does not state whether existing files are overwritten, whether directories must exist, or whether any interview state or permission prerequisites apply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the action, resource, and destination front-loaded. Every word earns its place; there is no filler or redundant restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no schema descriptions, no annotations, and no output schema, this description is not complete enough. It explains what the tool does but not how an agent should supply valid values for profile and output_path, nor what result to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 loosely maps 'one interview' to interview_id and 'local file path' to output_path, but it leaves the profile parameter completely unexplained and provides no path format, file extension, or optionality guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Download'), a precise resource ('PDF transcript for one interview'), and a clear destination ('local file path on the MCP host'). This distinguishes it from broader siblings like download_export_file or export_all_formats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for one interview' implies this is for single-interview PDF retrieval rather than bulk or multi-format exports. However, it never names alternatives or states when not to use this tool, leaving usage context implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does state the admin_write permission requirement, which is useful, but it omits details about side effects, reversibility, failure behavior for already-enabled workspaces, and return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The core action is front-loaded, and the permission requirement is stated in a second concise sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and zero parameter documentation, the description is too thin for a mutation tool. It does not explain the profile parameter, the outcome/return value, or conditions that affect the call, so an agent may not be fully equipped to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention either parameter (workspace_name or profile). The schema only provides names and types, so the agent gets no additional semantic guidance for correctly populating these parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Enable') and resource ('disabled Survey Solutions workspace'), clearly distinguishing this action from related workspace tools like create_workspace, disable_workspace, and delete_workspace. The object of the action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'disabled workspace' implies the tool should be used when a workspace is disabled, and 'Requires admin_write permission' gives a prerequisite. However, it does not explicitly state when not to use it or name alternatives such as disable_workspace or update_workspace.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden of disclosing side effects and input expectations. It only says 'Flag,' which suggests analysis but does not state whether data is modified, that a Tabular export must be supplied, or how findings are returned. The x_suso_qc schema block fills some of this metadata, but the description itself is too thin to be fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that leads with the action and scopes the tool precisely. The leading 'qc_duplicate_records:' prefix merely repeats the tool name and the word 'duplicate' occurs twice, but otherwise there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The x_suso_qc metadata compensates with methodology, output contract, exclusions, required export type, and minimum data requirements, so the description does not need to re-explain those. Still, with 8 parameters, no output schema, and no annotations, an agent relying on the description alone would lack enough context to assemble a correct call; only the schema metadata fills the gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% and the description adds meaning mainly to `variables` via 'user-supplied identifying variables.' It does not clarify `plan`, `profile`, `confirm_plan_id`, `questionnaire_identity`, or the relationship between `rules`, `thresholds`, and the duplicate logic, leaving half the parameters semantically opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Flag') and object ('duplicate interview IDs or duplicate combinations of user-supplied identifying variables'). The two input modes delineate what counts as a duplicate, distinguishing this QC tool from export and other QC siblings. The name prefix is redundant but does not obscure the meaning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for duplicate-detection QC work, but it never states when to prefer it over siblings such as qc_gps_duplicates_and_clusters or how it relates to other qc_* tools. No exclusions or alternative routing is provided, leaving the agent to infer applicability from the tool name and generic QC context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full behavioral disclosure burden, but it only reports the flagging outcome. It does not state non-mutating behavior, exclusions for missing or zero coordinates, decimal-degree methodology, output shape, or the required tabular export type. Those details are pushed into x_suso_qc rather than the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one tight sentence with the action front-loaded after the tool-name prefix. The only minor waste is the unnecessary repetition of the tool name before the colon, but overall it is concise and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The x_suso_qc block adds useful operational context: exclusion rules, output contract, required export type, and minimum data requirements. However, with 8 parameters, no annotations, no output schema, and several poorly documented fields like plan, profile, confirm_plan_id, and questionnaire_identity, the definition still leaves too much to inference for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions no parameter names, units, or semantics; 'tightly clustered' only vaguely evokes thresholds. Schema description coverage is 50%, so half the parameters have no schema description, and the free-text description does not compensate or clarify key parameters like cluster_radius_meters or duplicate_distance_meters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Flag') applied to a distinct resource ('repeated or tightly clustered GPS points') scoped 'across interviews.' This clearly distinguishes it from siblings like qc_duplicate_records (record-level duplicates) and qc_gps_accuracy_and_area (accuracy/area concerns).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for GPS duplicate/cluster QC but does not explicitly say when to use this tool versus alternatives. It names no when-not conditions or sibling alternatives. The x_suso_qc block supplies requirements like minimum data, but the description itself offers only implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for disclosing behavior. 'Guarded setup' hints at a dry-run/plan mode, but the description never explains what side effects occur when performed, whether resources are actually created, what 'manual Designer import' entails, or what a successful result looks like. The agent cannot predict the tool's real-world impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that conveys the tool's scope in a compact, well-structured list. There is no filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a multi-step operation with 6 parameters, no annotations, no output schema, and a large sibling set. The description names the components but omits required preconditions, step ordering, failure modes, return behavior, and the meaning of the default dry_run guard. For an orchestration tool, this leaves important gaps that prevent correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters, but it only loosely maps to workspace_name, questionnaire_name, and users. The critical dry_run parameter, plus profile and display_name, are left completely unexplained, leaving the agent without enough meaning to set them correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific action ('Plan or perform guarded setup') and a clear resource ('fieldwork project'), then enumerates the included components: workspace, Designer import, users, and first web-test assignment. This makes the tool's role as a higher-level setup orchestrator distinct from sibling tools like create_workspace, create_user, or create_assignment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Plan or perform guarded setup for a fieldwork project' implies when the tool is relevant, but it does not explicitly state when to choose this over individual setup tools, nor does it name alternatives. No exclusions or prerequisites are given, leaving the routing decision mostly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden and does disclose an important trait: export creation is allowed in read_only mode and does not alter fieldwork data. However, it does not mention async behavior, job lifecycle, or other side effects of starting an export.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences with no filler. The first states the core action and identity format; the second adds a meaningful permission caveat. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema or annotations, the description does not explain return values, how to poll for completion, or how this fits with sibling tools like list_export_jobs, get_export_job, and download_export_file. Multiple optional parameters remain unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only clarifies questionnaire_identity (GUID$Version). The other seven parameters, including from_utc, to_utc, profile, include_meta, interview_status, and paradata_reduced, receive no additional semantic explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Start') and resource ('Survey Solutions export job'), and gives an example identity format (GUID$Version). This distinguishes it from sibling tools like list_export_jobs, download_export_file, and cancel_export_job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as export_all_formats or export_and_combine_questionnaire_versions. The read_only note is permission context, not usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It does disclose an authorization requirement, which adds useful context beyond the schema. However, it does not mention error behavior, persistence, duplicate-name handling, or response/return details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The action is front-loaded, and the permission requirement is stated separately and clearly without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is workable for a simple create operation with required parameters already present in the schema. However, with no output schema, no annotations, and no mention of error or return behavior, the agent must guess what happens after a successful or failed call, leaving notable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%; profile and display_name are not described in the schema, and the description adds no parameter-level explanation. Only workspace_name has constraints in the schema, leaving the agent with limited guidance for the other parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Create a new Survey Solutions workspace.' It clearly differentiates this from sibling workspace lifecycle tools like update_workspace, delete_workspace, enable_workspace, and disable_workspace.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states a prerequisite ('Requires admin_write permission') but gives no explicit guidance on when to use this tool versus alternatives. The agent must infer from the name that this is the creation operation and that updates would go to update_workspace.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It adds useful context about permissions and the intended safe use case, but it does not disclose whether deletion is permanent, whether the workspace must be disabled first, or what consequences deleting a non-empty workspace would have.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and efficiently includes the permission requirement and safety condition. There is no wasted wording, and the key usage constraint is placed upfront.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations and no output schema, the description is thin on critical behavioral details like permanence, required prior workspace state, and what happens if the workspace is not empty. It mentions checking workspace status but does not say what status qualifies, leaving an agent to infer too much.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%), and the description adds no parameter-level meaning. It does not explain what workspace_name should contain beyond its name, nor does it clarify the purpose of profile or the confirmation parameter, even though confirm_workspace_name is already documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Delete') and the resource ('Survey Solutions workspace'), making the tool's purpose obvious. It does not explicitly differentiate from sibling workspace commands like disable_workspace or enable_workspace, but the deletion semantics are distinct enough that this is a minor gap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit preconditions: requires admin_write permission and should only be used for empty/test workspaces after checking workspace status. It does not name alternative tools for workspaces that are not empty, but the 'only for empty/test' condition effectively defines when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that the tool returns effective flags and that the profile defaults to active unless a specific profile is requested. However, it does not explain what flags are returned, whether this is read-only, or how "effective" is computed relative to permission modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 12-word sentence that front-loads the core purpose and includes the key behavioral distinction. Every word contributes; there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter and no output schema, so the description covers the main calling context. Still, it leaves gaps: the return shape of the "permission flags" is unspecified, and there is no mention of how this relates to permission modes or sibling permission-analysis tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents the optional "profile" parameter, and the description adds semantic value by clarifying that the active profile is used when omitted and a requested profile can be supplied. This default-vs-explicit behavior goes beyond the schema's minimal "Optional configured Survey Solutions profile name."
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb and resource: "Show effective permission flags" for the active or requested profile. The phrase "effective permission flags" distinguishes it from generic profile tools, though it does not explicitly differentiate from siblings like describe_permission_modes or get_active_profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by saying "active or requested profile," but it provides no explicit guidance on when to use this tool versus siblings such as describe_permission_modes, recommend_permission_mode, or get_active_profile. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. The word 'Fetch' implies a read-only operation and the explanation of surveySolutionsHeader adds useful output context, but the description does not explicitly state side-effect safety, required permissions, or potential 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The main purpose is front-loaded, and the second sentence adds a useful detail about a specific response field without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and no output schema, the description is mostly sufficient. It names what is returned and explains one key field, though 'capability summary' remains somewhat vague and no alternative or error context is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% because the only parameter, profile, is already described as 'Optional configured Survey Solutions profile name.' The description reinforces that the active profile is used but adds no additional semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Fetch') and resource ('basic Survey Solutions server information and capability summary') scoped to the active profile. However, it does not explicitly distinguish itself from the sibling tool get_api_capabilities, which could overlap with 'capability summary.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives like get_api_capabilities or check_connection. The phrase 'for the active profile' provides some context, but there are no explicit when-to-use, when-not-to-use, or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the disclosure burden. It adds useful context about collected/in-progress cases and the caveat that filter availability depends on the Headquarters build. However, it does not disclose pagination behavior, permissions, rate limits, or the response envelope, which are relevant for a list operation with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with no filler. The main action is front-loaded, and the second sentence adds valuable context about the interview set and filter variability without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no annotations and no output schema, the description gives a reasonably complete picture: what is listed, what fields are present, and a key caveat about filter support. It lacks explicit mention of pagination or return structure, but the schema covers limit/offset and the description covers the item contents, so the gap is moderate rather than severe.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so the baseline is 3. The description adds only a general caveat about filter availability depending on the build; the schema already documents limit, offset, status, questionnaire_identity, and query. It does not enrich understanding of the 'profile' parameter or the advanced query object beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb ('List'), a clear resource ('Survey Solutions interviews'), and a scope ('active workspace interview list endpoint'). It also describes the content returned (ID/key/status/responsible user/history). It does not explicitly name sibling tools for differentiation, but the distinction from get_interview_details and list_assignments is reasonably inferable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus siblings such as list_assignments, get_interview_details, or get_interview_history. It mentions that filters depend on the Headquarters build, but does not state when this tool is the right choice or when an alternative should be selected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does disclose the admin_write permission requirement, which is meaningful behavioral context beyond a bare mutation statement. However, with no annotations, it does not describe side effects, reversibility, return behavior, or whether the optional profile parameter changes behavior. This is adequate but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The primary action is stated first, followed by the permission precondition. Every sentence carries useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple, but the description omits the purpose of the profile parameter and provides no output or postcondition information. The permission note helps, but without annotations or an output schema, the definition leaves several details that an agent may need for a fully confident call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 for undocumented parameters. It clarifies that display_name is the target field, and workspace_name is reasonably inferable as the identifier, but the optional profile parameter is completely unexplained. The description does not fully 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update') and a specific resource ('workspace display name'), which clearly distinguishes this from sibling tools like create_workspace, disable_workspace, or delete_workspace. The permission requirement adds further precision, so an agent can identify the tool's intent immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance about when to use this tool versus alternatives, nor any exclusions. It does not mention that this is for existing workspaces only, how it differs from create_workspace or delete_workspace, or any conditions such as workspace state. Usage context is only implied by the tool name and target field.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does usefully state permission requirements and the mandatory exact identity confirmation. However, it does not disclose side effects, reversibility, or impact on active interview sessions or links after deactivation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is one compact sentence, front-loading the action and then adding only the essential requirements. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a basic mutation tool, covering action, permissions, and confirmation. However, it omits consequences of deactivation and how to verify state afterward, and it gives no guidance on the profile parameter, leaving the operational picture incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents questionnaire_identity as GUID$Version and confirm_questionnaire_identity as an exact match, so the description mostly reinforces existing schema information. The optional profile parameter is undocumented in both schema and description, leaving a semantic gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Deactivate') and a clear resource ('questionnaire-level web interviews'), making the action unambiguous. It is also easily distinguished from sibling tools like activate_web_interview and get_questionnaire_web_interview_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives prerequisites (permission and identity confirmation) but does not explain when to choose this tool over activate_web_interview or get_questionnaire_web_interview_status. There is no explicit when-to-use or when-not-to-use guidance beyond the action itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal the key side effect: the tool writes a downloaded file to a local path on the MCP host. However, it does not mention whether an existing file is overwritten, whether directories are created, what happens if the output_path is omitted, or what kind of response is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that states the action, target resource, and destination with no filler. Every word contributes to the agent's understanding of the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no annotations and no output schema, so the description should provide the missing context. It fails to clarify that only job_id is required while output_path is optional, leaving ambiguous where the file is written if output_path is omitted. It also does not explain the profile parameter, making parameter usage for full invocation incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, and the description adds no parameter-level meaning. job_id and profile are left undocumented in both the schema and the description, while output_path is the only parameter that already has schema documentation. The description does not explain what profile refers to or how the optional output_path behavior works.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (download), a specific resource (a completed Survey Solutions export job), and a concrete destination (a local file path on the MCP host). This clearly distinguishes it from sibling tools like inspect_export_file or get_export_job, which deal with viewing or checking jobs rather than retrieving the file to disk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'completed' implies this tool should only be used after an export job has finished, giving some contextual timing guidance. However, there is no explicit mention of when not to use it, what to use instead for checking status or starting a job, or any prerequisite steps such as calling start_export or get_export_job first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Get available answer/detail values' without stating read-only behavior, output shape, error behavior, or any prerequisites. It does not go beyond what the tool name alone implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The primary function is front-loaded, and the alternative guidance is placed second, making it easy to parse and act on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool without output schema, the description is adequate for basic invocation and sibling routing, but it leaves gaps: it does not describe what 'answer/detail values' concretely contain, what profile means, or what the response looks like. It is enough to get started but not fully complete for a confident call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 interview_id identifies the interview, but it completely ignores the 'profile' parameter and gives no semantics for it. Half of the parameters remain undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific action ('Get available answer/detail values') and resource ('one interview by interview ID'). It also distinguishes itself from get_interview_history and get_interview_stats by assigning them to audit trail, status changes, comments, and counts. However, the phrase 'answer/detail values' remains somewhat vague and could be more precise about what is actually returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly routes the agent to relevant siblings: 'Use get_interview_history and get_interview_stats for audit trail, status changes, comments, and operational counts.' This gives clear when-to-use versus when-to-prefer-alternatives guidance, which is particularly valuable given the large sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden of behavioral disclosure. It specifies the scope and content of the returned records and notes that results come from the 'active Headquarters build,' which is moderately informative. It does not describe output format, pagination, ordering, or permissions, but for a read-only history lookup the stated content coverage is a reasonable baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and resource, then adds concrete detail about the record types included. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and complete parameter documentation coverage, the description should clarify the role of profile and give some indication of the response shape or limits. It lists the kinds of history records included but omits the profile parameter and does not describe the return structure, leaving an agent without enough information to confidently invoke the tool with all parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description must compensate for the missing parameter docs. It indirectly clarifies that interview_id identifies the target interview ('for one interview'), but it entirely fails to explain the optional profile parameter, leaving a significant semantic gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a specific resource ('audit/history records for one interview'), and it enumerates the record types included: status changes, answers, comments, and assignment actions. This clearly differentiates it from siblings like get_assignment_history and get_interview_details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving audit/history data for a single interview, which provides some usage context. However, it does not state when to prefer this over related tools such as get_assignment_history or get_interview_details, nor does it mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It transparently discloses that it avoids parsing binary Stata/SPSS data, which is genuinely useful, but it omits the side-effect that the extract parameter can unpack files into output_dir or a sibling folder. The 'inspect' framing could misleadingly suggest a purely read-only operation despite a write-capable extract mode.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, dense sentence conveys the tool's purpose, scope, operations, and a key limitation without filler. Every clause earns its place and the core action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose well but is incomplete for a 7-parameter tool with no annotations and no output schema. It does not describe the returned preview/summary structure, and it fails to mention the extract side-effect that writes files, which an agent needs to anticipate before invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 seven parameters thoroughly. The description adds general context about listing and sampling metadata, but it does not add meaning beyond the schema for extract, output_dir, sample_rows, include_details, or other parameters, matching the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the specific verb and resource: inspect a downloaded Survey Solutions export zip on the MCP host. It enumerates concrete actions (list files, classify file types, sample metadata) and explicitly excludes binary Stata/SPSS parsing, which distinguishes it from export and download siblings, though it never names those alternatives directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for post-download, pre-analysis inspection of a local export zip, but it does not explicitly state when to choose it over related tools like download_export_file, export_all_formats, or prepare_latest_export_for_analysis. The context is clear but exclusionary guidance 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does add two behavioral facts: the list is scoped to the active workspace, and exports are asynchronous. It does not disclose whether the list includes statuses, whether it is read-only, or whether pagination/filtering exists, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, with the core purpose front-loaded and the async workflow note earning its place. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the export lifecycle and workspace scoping, which is useful for invoking the tool. Since there is no output schema, the agent is not told what fields the listing returns (e.g., job IDs/statuses needed for polling), so the picture is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the optional 'profile' parameter is already documented in the schema. The description adds no detail about how the profile affects the active-workspace scoping, but the high coverage makes that acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('List') and resource ('Survey Solutions export jobs') with a workspace scope, so an agent can identify what the tool does. It is not explicit about how it differs from sibling get_export_job, though plural 'jobs' and 'list' signal a collection operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence gives useful workflow context—exports are asynchronous, so listing jobs is part of a start/poll/download sequence. However, it never states when to prefer this tool over get_export_job, start_export, or cancel_export_job, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It clearly indicates a read-only listing operation and scopes it to 'imported' questionnaires, but it does not describe output structure, ordering, pagination, or whether archived/draft versions are included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the operation. The versioning explanation earns its place by giving the agent a reason why the listing matters, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with one optional parameter, the description plus schema likely suffice for basic invocation. However, since there is no output schema and no annotations, the description could be more complete about what each returned version entry contains or how the optional profile affects results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the one optional 'profile' parameter is already documented. The description adds no additional semantic detail about how the profile affects results, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List imported questionnaires and versions.' This clearly identifies the tool's core function and scope, but it does not explicitly differentiate it from version-related siblings like compare_questionnaire_versions or export_all_questionnaire_versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence provides useful context: versioning matters because fieldwork changes create new versions with different schemas. This implies the tool is useful for discovering available versions before version-sensitive operations, but it does not explicitly state when to use this tool over alternatives or list exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden, and it does add useful context: it checks API capabilities first and applies the same raw API permission rules as rest_request for writes. It does not describe potential side effects, response behavior, or failure modes of a raw REST execution.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the core action and then add the important permission/capability context. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a raw REST operation with six parameters and no output schema or annotations, the description is too thin. It provides a capability-checking detail but omits parameter semantics, return shape, and error/edge-case behavior, leaving an agent under-equipped to call it safely and effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description only mentions method and path. The body, query, profile, and refresh parameters are left undocumented, and the description does not compensate for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Execute a REST operation'), a resource ('by method/path'), and a distinguishing trait: a 'curated escape hatch' that shares rest_request's raw permission rules. This makes its purpose and relationship to the rest_request sibling clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It identifies the tool as an escape hatch, which implies use when no dedicated tool covers an operation. However, it does not explicitly state when to choose openapi_operation over rest_request or other siblings, nor give exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It adds a useful permission requirement and constrains the target users to supervisors/interviewers. But it omits behavioral preconditions (e.g., the user must currently be archived) and side effects (e.g., restoring access), leaving some uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence that front-loads the action and object, followed by a concise permission note. Every word earns its place and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, no annotations, and two parameters with one unexplained. The description does not clarify the 'profile' parameter, the expected response, or prerequisites beyond permission, so an agent lacks enough context for fully correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needed to clarify the parameters. It indirectly clarifies user_id by limiting it to supervisor/interviewer users, but the optional 'profile' parameter is not explained at all, leaving its purpose and format ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the specific action 'unarchive' and the resource 'supervisor or interviewer user'. This clearly differentiates from sibling tools like archive_user and create_user based on the inverse action and user-type scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is used when an archived supervisor/interviewer needs to be restored, and it notes the admin_write permission requirement. However, it does not explicitly contrast with archive_user or state when not to use this tool, so the selection context must be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the required permissions (fieldwork_write or admin_write) and the relationship to the HQ endpoint, which is useful auth/scoping context. It does not describe side effects, idempotency, whether the questionnaire must already be configured for web interviews, or what happens if web interviews are already active.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff; the core action is first and the authorization constraint is second. Every clause carries useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description includes the key scope and permission context. Still, it leaves ambiguity about the activation effect, preconditions, and the profile parameter, so it is not fully complete for an agent deciding to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%, with the required questionnaire_identity documented in the schema and the optional profile left as a bare string. The description adds no parameter-level information and does not compensate for the undocumented profile parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific action (activate), a precise object (questionnaire-level web interviews), and the mechanism (same HQ endpoint used by Web Interview Settings). This clearly distinguishes it from sibling tools like deactivate_web_interview and get_questionnaire_web_interview_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The permission requirement gives a precondition, and 'same HQ endpoint used by Web Interview Settings' implies the programmatic equivalent of that UI action. However, it does not explicitly state when to prefer this tool over alternatives such as deactivate_web_interview or when activation is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It does disclose an important behavior: for the mock profile, it returns a mock success result rather than performing a real authentication check. However, it does not describe possible failure modes, side effects, or what happens when no profile is selected or when the profile is invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no fluff. The core action is front-loaded, and the mock-profile special case is stated separately and clearly. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only connectivity check with one optional parameter and no output schema, the description covers the essential behavior including the important mock-profile exception. It could be slightly more complete by stating the expected result for real profiles, but the agent can reasonably infer success/failure from the stated purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the single optional profile parameter, so the description need not repeat it. The description adds useful context by referring to 'selected profile' and 'mock profile', helping the agent understand how the optional parameter relates to active profile selection, but it doesn't add significant new syntax or format detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Verify') and resource ('selected profile can reach and authenticate with Survey Solutions Headquarters'), making the tool's function unambiguous. It also distinguishes itself from the large sibling set by focusing on connectivity/authentication rather than data operations or server info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used to check profile connectivity/auth, but it provides no explicit when-to-use guidance, prerequistes, or alternatives. It does not mention when to choose check_connection over related tools like get_server_info or list_profiles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, 'Read' at least signals a non-mutating operation. However, it does not disclose error behavior, auth/profile requirements, or what the response will look like, so transparency is only partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Seven words, single sentence, front-loaded with verb and object; no waste. It covers the core semantics without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read, the core call is inferable (assignment_id), but the profile parameter and return value are not described and there are no annotations or output schema to fill the gaps. Adequate for basic usage but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage) and the tool text only hints at assignment_id via 'one assignment.' The optional profile parameter is entirely unexplained, so the description does not compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Uses a specific verb ('Read') and resource ('audio-recording setting') scoped to 'one assignment.' This clearly separates it from the write sibling set_assignment_audio_recording and from the questionnaire-level get_questionnaire_audio_recording.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for reading an assignment-level setting, but it does not explicitly say when to choose it over set_assignment_audio_recording or get_questionnaire_audio_recording, nor does it state exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. 'Read' clearly signals a non-mutating operation, and 'where supported by the active Headquarters build' warns about conditional availability. It does not mention permissions, error behavior, or the exact shape of the returned settings, but the read-only behavior is sufficiently conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes: the verb, the resource, and the availability caveat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with no output schema, the description is mostly adequate: it names the resource and a key availability constraint. However, it leaves the agent without detail on what the returned audio-recording settings look like, how the optional profile affects the request, or what happens when the build does not support the feature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%: questionnaire_identity is documented in the schema, but the optional 'profile' parameter has no description. The description itself adds no parameter-level meaning, so it fails to compensate for the undocumented profile parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Read'), a specific resource ('questionnaire audio-recording settings'), and a scope condition ('where supported by the active Headquarters build'). This clearly distinguishes it from sibling tools like set_questionnaire_audio_recording and get_assignment_audio_recording.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need to read questionnaire-level audio-recording settings. However, it does not explicitly mention alternatives or state when not to use it, leaving the agent to infer the distinction from the verbose sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. 'Check whether' implies a read-only operation, and the consequence about expired links adds useful context. However, it does not explicitly state that the tool has no side effects, return format, or access requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler, front-loading the core purpose and adding one valuable consequence. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but with no output schema and no annotations the description should at least indicate what the status result looks like or how the optional profile affects the call. It provides the key business consequence but omits return-value and request-context details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents questionnaire_identity but leaves profile undocumented, giving 50% schema coverage. The description adds no parameter meaning and does not help clarify the optional profile parameter, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Check whether questionnaire-level web interview mode is active.' This clearly distinguishes it from sibling tools like activate_web_interview and deactivate_web_interview, which change state rather than inspect it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a use case by noting that inactive mode may cause web assignment links to appear expired, but it does not explicitly say when to use this tool over alternatives or mention any exclusions. Usage context is present but only by implication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It conveys that the tool is explanatory and safety-oriented, but it does not disclose what the output format will be, whether any state is read, or how the detail_level parameter affects the response. For a non-mutating tool the gap is less severe, but still incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with zero waste. It front-loads the verb and then provides a useful, compact list of covered topics. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two optional parameters and no output schema, but the description gives no guidance on how to select detail_level or whether to request examples. It adequately explains the overall purpose but omits enough operational detail for an agent to make fully informed invocation choices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention detail_level or include_examples at all. The parameter names and enum values are somewhat self-explanatory, but the description fails to add any additional meaning or usage guidance, so it does not compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Explain') and a specific resource ('Survey Solutions concepts and safe MCP usage') and enumerates the exact topics covered. This makes it easily distinguishable from the many operational sibling tools that perform actions rather than provide orientation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context of when to use this tool is implied: it is for understanding concepts and safe usage rather than performing operations. However, the description does not explicitly state when to use this tool instead of related explanatory siblings like describe_permission_modes, get_api_capabilities, or explain_blocked_tool, nor does it provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden. It does disclose that this is a gated mutation requiring explicit approval, fieldwork_write/admin_write, and exact batch confirmation. However, it does not describe what applying the batch actually changes, whether it is reversible, or what side effects may occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence conveys the action, the prerequisite, the required permissions, and the confirmation requirement. Every phrase earns its place, 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters, a nested object, 0% schema coverage, and no output schema, this description is too sparse. It omits the batch object structure, the role of profile, the meaning of max_actions, and what a successful application returns or looks like. It earns a 2 rather than a 1 because the approval/permission prerequisites are useful and actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needed to compensate. It only gives vague meaning to 'batch' (a prepared feedback batch) and 'confirm_batch_id' (exact batch confirmation), while 'profile' and 'max_actions' remain entirely unexplained. The nested batch object structure is also undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Apply') and a specific resource ('prepared feedback batch'), and the qualifier 'prepared' plus 'after explicit approval' clearly distinguishes it from its sibling prepare_qc_feedback_batch. An agent can immediately understand this is the execution counterpart to the preparation step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 the tool: after explicit approval, with the required permission level, and with exact batch confirmation. It does not explicitly enumerate exclusions or name alternative tools, but the 'prepared batch' qualifier makes the relationship to prepare_qc_feedback_batch evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose meaningful behavior: it prepares a plan rather than downloading/combining, and it treats later-added variables as structurally missing in earlier versions. However, it omits side effects, whether the plan is returned or written to output_dir, and any required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the core action and scope before adding the version-missingness detail. Every phrase contributes semantic value with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a required path array and an output_dir, yet neither is described, and there is no output schema or return-value description. The description conveys the concept but leaves out the operational details an agent needs to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no meaning for either parameter. 'Already downloaded exports' weakly implies export_paths, but output_dir is completely unexplained, so the agent must guess or inspect further to call the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Prepare a ... combine plan') on a specific resource ('already downloaded exports') and adds the version-aware behavior of treating later-added variables as structurally missing in earlier versions. This clearly contrasts with sibling export-and-combine tools, which still need to download exports first.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Already downloaded exports' gives the agent a clear precondition that separates this tool from export_and_combine_questionnaire_versions and export_and_combine_all_versions_all_formats. It does not explicitly name alternatives or add a when-not-to-use rule, but the context is specific enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that this is a delete operation, names the required permission level, requires exact confirmation of the interview ID, and notes that support depends on the active Headquarters build. This goes well beyond a simple 'Delete an interview' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: the action, the safety requirements, and the usage restriction. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations and low schema coverage, the description covers permissions, confirmation, and test-only usage, which is good. However, it leaves the optional comment and profile parameters unexplained and does not clarify what happens when the active Headquarters build does not support deletion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, and the description does not compensate. 'Exact interview confirmation' adds little beyond the schema's own confirm_interview_id description, and the optional comment and profile parameters are left completely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Delete an interview'. It is clear and distinct from siblings such as list_interviews or approve_interview, though it does not explicitly name any sibling for differentiation and adds a conditional caveat about the active Headquarters build.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: requires fieldwork_write/admin_write, requires exact interview confirmation, and 'Use only on throwaway/test cases' is an explicit when-not condition. It does not name an alternative tool for production deletions, but the restriction is strong and practical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It does disclose that connection details are redacted, which is security-relevant, and 'Return' implies a read operation. However, it says nothing about error behavior, whether a profile must already be active, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One clear sentence with the action front-loaded and no filler. Every word contributes to the core purpose and the redaction caveat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter query the description is mostly sufficient, but there is no output schema and the return shape is only vaguely described as 'profile and redacted connection details'. An agent is left unsure what fields will be present beyond a generic profile object.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, and the input schema is already complete. With no parameters to document, the description cannot add parameter-level meaning, so the zero-parameter baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact verb ('Return') and a specific resource: the currently active Survey Solutions profile, plus redacted connection details. This clearly distinguishes it from siblings like list_profiles or set_active_profile, which enumerate or change profiles rather than retrieve the active one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance, prerequisites, or alternatives. It never mentions list_profiles or set_active_profile, so an agent receives no help choosing among profile-related tools beyond the tool name and the word 'active'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It implies a read-only inspection operation through 'check' and 'inspect', but it does not explicitly state that it does not modify state, nor does it explain what counts are returned or how the result is structured. Some transparency, but not complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, tightly worded sentence that front-loads the core purpose and adds the deletion context. No filler or repetition; every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no annotations and no output schema, so the description alone must provide enough context. It covers the high-level purpose but omits the meaning of 'blocking counts', the response shape, the role of the profile parameter, and behavior when the workspace does not exist or cannot be found.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate for the two parameters. 'workspace' hints at workspace_name, but 'profile' is entirely unexplained, and there is no guidance about required versus optional usage or expected value formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('check') and resource ('workspace'), and narrows the purpose precisely: determining whether deletion is possible and viewing blocking counts. This clearly distinguishes it from delete_workspace and list_workspaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly frames the tool as a pre-deletion check ('before deletion'), giving clear context for when it should be used. It does not mention exclusions or name an alternative, but the usage context is strong enough to route an agent correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It makes clear this is a read-only listing operation scoped to statistics-reporting-eligible questions and names the underlying OpenAPI endpoint. However, it does not describe response shape, pagination, permissions, or error behavior, so some behavioral ambiguity remains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with the core purpose front-loaded. The OpenAPI endpoint detail is slightly implementation-focused but does not add meaningful clutter, and the description remains appropriately short for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple one-required-param list tool: the agent knows what it returns conceptually and what parameter is needed. However, because there is no output schema or annotations, the description should ideally clarify the return format and the role of the optional profile parameter; those gaps prevent a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, and the optional 'profile' parameter is left completely undocumented. The description's mention of 'questionnaireId/version query parameters' does not map cleanly to the actual MCP parameters ('questionnaire_identity' and 'profile'), and it does not explain the optional parameter or the identity format beyond what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise action ('List questions') and a specific resource ('questions available to Survey Solutions statistics reporting for a questionnaire'). This clearly distinguishes it from siblings like list_statistics_questionnaires and list_questionnaires because the resource is explicitly 'questions' scoped to a single questionnaire.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use the tool: when you need the set of questions eligible for statistics reporting for a specific questionnaire. It does not name alternatives or state exclusions, but the domain scoping is strong enough for an agent to select it correctly among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral burden. It transparently indicates that the tool does not perform an import itself but prepares instructions for a human to execute, and it discloses the relevant context of missing public API availability. It could add more detail about the expected output format, but the core non-mutating behavior is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly written sentence that leads with the action and states the essential condition. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for tool selection but incomplete for correct invocation: it does not describe what the generated instructions look like, how they are returned, or how the five parameters should be populated. With no output schema and no annotation support, this is a meaningful gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no meaning for any of the five parameters. Parameter names like workspace_name, profile, import_comment, questionnaire_name, and after_import_next_steps are left entirely unexplained, so an agent cannot determine what values to supply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Prepare') and a specific resource ('human-in-the-loop instructions for importing a questionnaire from Designer into Headquarters'). It also states the key condition ('when no public import API is available'), which distinguishes it from any potential direct-import sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when the tool is appropriate: when no public import API is available. It provides a clear context for use, though it does not explicitly name alternatives or exclusion cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does disclose that this is a 'Live mutation', requires permissions, and advises reading current status first. However, it does not describe the side effects of rejection, reversibility, or what the response looks like, leaving meaningful behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the purpose is front-loaded, followed by permission, confirmation, and usage guidance. Every phrase earns its place and the structure is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description covers key requirements like permissions and confirmation, but it omits what happens after rejection, possible preconditions for valid status, and any return/result information. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, and the description adds some value by reinforcing 'exact interview ID confirmation' and advising a clear comment. It does not explain the 'profile' parameter and only partially compensates for the undocumented parameters, though responsible_id is already well covered in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Reject'), a clear resource ('an interview'), and an actor ('as supervisor'), which distinguishes it from generic rejection tools. However, it does not explicitly differentiate itself from sibling hq_reject_interview beyond the supervisor hint, so it falls just short of a top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for use: supervisor-level rejection, required permissions, and an instruction to read current status first. It does not explicitly state when not to use it or point to an alternative such as hq_reject_interview, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It correctly signals that this is a mutating operation and mentions permission requirements and a confirmation guard. However, it does not describe side effects, reversibility, idempotency, or what happens once the flag is set.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The action is front-loaded, and the second sentence adds essential preconditions. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation with 4 parameters, 0% schema coverage, no annotations, and no output schema, the description is too sparse. An agent cannot reliably determine how confirm_assignment_id should be used, what enabled controls, or how profile affects the call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 for missing parameter explanations. It only vaguely references 'exact assignment confirmation', which maps to confirm_assignment_id, but it does not explain enabled semantics, the role of profile, or the requirement that confirmation must match assignment_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Set'), a specific resource ('assignment audio-recording flag'), and the operation's nature. It also distinguishes itself from related siblings such as get_assignment_audio_recording (read vs. write) and set_questionnaire_audio_recording (assignment vs. questionnaire).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by naming required permissions (fieldwork_write/admin_write) and a safety prerequisite (exact assignment confirmation). It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to understand when this write operation applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the auth requirement ('admin_write permission') and a safety behavior ('exact questionnaire identity confirmation'). However, it does not describe side effects, whether existing settings are overwritten, or what the tool returns, leaving significant behavioral aspects undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with the core action front-loaded and the prerequisites as a clear second sentence. Every phrase earns its place; there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has four parameters, two lacking schema descriptions, and no output schema. The description does not explain the meaning or values of 'enabled' and 'profile', nor the tool's return behavior, leaving an agent without enough information to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, with 'enabled' and 'profile' undocumented. The description adds no meaning for these parameters and only restates the schema's existing confirmation requirement for 'confirm_questionnaire_identity'. 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and a specific resource ('questionnaire audio-recording settings'), clearly distinguishing this tool from its getter counterpart (get_questionnaire_audio_recording) and the assignment-level sibling (set_assignment_audio_recording). It is direct and not tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating the required 'admin_write permission' and the need for 'exact questionnaire identity confirmation', which helps an agent decide whether it can and should call this tool. It does not explicitly name alternatives or exclusions, but the resource scope is unambiguous, making the intended usage evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full disclosure burden and handles it well: 'Live mutation' signals side effects, the permission list states authorization preconditions, and 'expect the returned state/audit fields to vary by Headquarters build' flags unstable return values. It stops short of describing what state an approval transitions the interview into or whether the action is reversible, but this is strong behavioral disclosure for an annotation-free tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three front-loaded sentences, each earning its place: core action first, then permission and confirmation-guard requirements, then the live-mutation warning with a return-value caveat. No filler, no restatement of the tool name or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, authorization, the confirmation guard, side-effect nature, a read-first precondition, and a return-value caveat — strong for a 4-parameter mutation with no annotations and no output schema. The remaining gaps are the unexplained comment/profile parameters and the lack of an explicit nod to the reject_interview or hq_approve_interview alternatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% — confirm_interview_id is the only documented parameter ('Must exactly match interview_id') — and the description's 'exact interview ID confirmation' largely restates that same schema constraint rather than adding new meaning. comment and profile receive no explanation in either the schema or the description, leaving the 75% coverage gap uncompensated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the action and actor plainly — 'Approve an interview as supervisor' — with a specific verb and resource. The supervisor role plus the fieldwork_write/admin_write permission hint distinguishes this from the HQ-level approval siblings like hq_approve_interview, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete usage context: permission prerequisites ('Requires fieldwork_write or admin_write permission'), a safety precondition ('read current status first'), and a live-mutation warning. It never names the alternative tools or states when-not-to-use, so routing away from reject_interview or the hq_* variants is left to implication rather than explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose a permission requirement and a confirmation safeguard. However, it does not explain what 'exact assignment confirmation' means in practice, nor what side effects or postconditions reassignment has.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The action is front-loaded and the permission/confirmation constraints are stated directly afterward.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the action and a key safety requirement, but with no annotations and no output schema it leaves important operational details unresolved: what 'exact assignment confirmation' means for the parameters, what 'profile' is, and what the result or failure behavior looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 hints that 'responsible' is the target user and that confirmation is required, but it leaves 'profile' completely unexplained and does not clarify that 'confirm_assignment_id' should likely match 'assignment_id'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Reassign') with a clear resource ('an assignment') and target ('another responsible user'). It is easily distinguished from sibling tools like create_assignment, archive_assignment, or change_assignment_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The action itself makes the primary use case clear: use this when an assignment should be moved to a different responsible user. It also states required permissions, giving access context, though it does not explicitly name alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does disclose the mutating nature of the operation and the required admin_write permission, which is meaningful. However, it does not mention side effects, reversibility, behavior when no notice exists, or what response to expect, leaving gaps for a destructive admin action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no redundant wording. The core action is front-loaded, and the permission requirement earns its place as actionable context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-action admin tool with a single optional parameter, the description covers the essential context: what is removed and what permission is required. The schema handles the parameter, and no output schema exists, so return-value details are not critical here. Minor omissions like idempotency or no-op behavior prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter, 'profile', with 100% coverage, so the schema carries the semantic weight. The description adds no parameter-level details, which is acceptable given the parameter is optional and already documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') with an exact resource ('Survey Solutions Headquarters global notice'), making the action unmistakable. It also differentiates naturally from sibling tools like set_global_notice and get_global_notice by describing a removal rather than a creation or retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the verb 'Remove' and the resource name, but there is no explicit guidance about when to choose this tool over get_global_notice or set_global_notice. The permission note is useful but does not provide usage context, alternatives, or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the behavioral burden. It explicitly disclaims a serious hidden behavior: 'The MCP does not silently grant itself more permission,' which tells the agent this tool returns instructions rather than applying changes. It could add more detail about return presentation or prerequisites, but the core behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler; the action and deliverable are front-loaded. The second sentence adds a meaningful behavioral caveat that earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter generator with no output schema, the description is mostly adequate but leaves gaps: no guidance on how the caller should set target_permission_mode, no indication of whether both bash and PowerShell are always returned, and no explicit statement of the output format. It gives the agent enough to select the tool but not to fully anticipate its response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needed to explain the parameters, but it only echoes the field names: 'profile' and 'permission mode.' It does not elaborate on target_permission_mode's enum values (read_only, fieldwork_write, admin_write, raw_api) or how the command uses them. The agent must rely on the raw schema field names and enums.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Generate'), a concrete resource ('profile's permission mode'), and the deliverable (bash/PowerShell command). It clearly distinguishes this from sibling permission-related tools like describe_permission_modes or get_profile_permissions by emphasizing that it produces a command for the user rather than inspecting or recommending modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance and no sibling alternatives are named. The phrase 'a user can run' implies the intended scenario—providing the user a self-service command—but exclusion or comparison with recommend_permission_mode is left to the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It adds meaningful safety context by explicitly stating 'Does not expose secrets' and listing that the operation is a read-only return of diagnostics. It could go further by explicitly stating no side effects, but the wording strongly implies a non-mutating diagnostic call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the first front-loads the tool's purpose and its full output contents, and the second adds a worthwhile security-relevant caveat. Every sentence earns its place, and the structure is easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema diagnostic tool, the description is complete: it states what the tool is for, exactly what information it returns, and that it does not leak secrets. There are no hidden parameters or complex output structures that would require additional explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter semantics to document. The description compensates by listing what the output will include, which is the relevant semantic information for a no-input diagnostic tool. The baseline for zero-parameter tools is 4, and nothing is lost by the schema being empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('Return MCP package/runtime diagnostics') and enumerates the exact diagnostic fields, so an agent understands both the action and the subject matter. It does not explicitly name or distinguish itself from sibling diagnostic-oriented tools such as get_server_info or check_connection, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool returns but does not say when to use it, when not to use it, or which sibling tools might be more appropriate for related needs. There is no explicit or implicit guidance for choosing between this and other diagnostic/inspection tools like get_server_info, get_active_profile, or check_connection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral disclosure burden. It clearly states that this is a read operation and adds a feature-availability caveat, but it does not describe the output shape, error behavior when unsupported, or any permission requirements. For a simple getter, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that states the action, the resource, and the key availability condition. Every word contributes, and it is appropriately front-loaded with the verb and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a low-complexity read tool, but with no output schema and no annotations, the agent is missing information about the return value and the meaning of the optional profile parameter. The description is not misleading but is not fully complete for a tool with an undocumented parameter and no output specification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%; questionnaire_identity is documented as 'GUID$Version format', but the optional profile parameter has no schema description. The tool description does not compensate by explaining what profile means or how it affects the read, leaving the agent to guess about half the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and resource ('questionnaire criticality settings'), making the tool's function immediately clear. It also adds a scoping condition ('where supported by the active Headquarters build') that distinguishes it from its write sibling set_questionnaire_criticality_level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by framing this as a read operation conditioned on Headquarters build support. It does not explicitly name alternatives or exclusions, but the read versus set distinction is implicit from the sibling tools and the verb choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that this is a 'Live mutation,' warns to 'read current status first,' states required permissions, and flags that returned state/audit fields vary by build. This gives an agent concrete behavioral expectations for a side-effecting operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and well-structured: action first, then permissions, then behavioral warnings. Every clause earns its place and there is no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description covers the essential operational context: who can call it, what to check first, and what kind of output variability to expect. It is slightly incomplete because comment and profile parameters are never explained, and sibling-tool routing is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, and the description does not compensate for the undocumented comment and profile parameters. It reinforces the 'exact interview ID confirmation' requirement for confirm_interview_id, but that is already stated in the schema, so little additional meaning is added beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Approve an interview as Headquarters.' It adds role and permission context that goes beyond the tool name, but it does not explicitly contrast with the closely related sibling approve_interview, so differentiation is left mostly to the phrase 'as Headquarters.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context: an HQ user with fieldwork_write or admin_write permission performing a live approval after reading current status. However, it never states when not to use this tool or points to alternatives like approve_interview or hq_unapprove_interview.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description itself must convey behavioral expectations. It does clarify that this lists only workspaces available to the configured API user, which is helpful, but it does not disclose return format, pagination, ordering, or what happens when no workspaces exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, purposeful sentences: the first states the operation and scope, the second adds useful domain context. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, low-complexity list operation with only one optional parameter, the description is sufficiently complete for an agent to call it correctly. It could mention what information is returned, but the absence of an output schema makes that a minor gap rather than a substantial one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single optional profile parameter is already self-explanatory in the schema. The description does not add additional meaning about how the profile affects the listing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List') applied to a clearly defined resource ('Survey Solutions workspaces available to the configured API user'), and clarifies what a workspace is. This distinguishes it from sibling tools like create_workspace, disable_workspace, and list_profiles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context that workspaces are logical areas inside Headquarters gives some implied sense of when listing would be useful, but no explicit when-to-use or when-not-to-use guidance is provided. It does not mention alternatives or conditions for using the optional profile parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the operation writes local configuration and explicitly states what it does NOT change (credentials, permissions, server data), which is valuable for setting agent expectations about side effects. However, it does not mention reversibility, authentication requirements, or potential errors, so it is not fully transparent but exceeds a minimal description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The action and core scope are front-loaded in the first sentence, and the second sentence clarifies boundaries. Every word earns its place; it is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple config-switching tool with one parameter and no output schema, the description covers the main purpose and side-effect scope. However, it omits practical context such as how to discover valid profile names (e.g., via list_profiles), what happens if the profile does not exist, and whether the operation returns a success indicator. These gaps leave an agent to infer essential call details, so completeness is only partial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the single 'profile' parameter, and the description does not compensate. It refers to 'active profile' but gives no details on valid values, format, or how to obtain them (e.g., from list_profiles). The only hint is that the parameter represents the profile to make active, but that's minimally inferred. This is insufficient for a parameter with no schema-level documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Switch') and resource ('active profile'), and clearly delimits scope to the MCP server's local config, distinguishing it from siblings like get_active_profile (read) and list_profiles (list). It also explicitly excludes changes to credentials, permissions, or server data, leaving no ambiguity about its function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when you want to switch profiles) but does not compare against alternatives or state exclusions. It does not mention that list_profiles can retrieve valid profile names or that get_active_profile shows the current one. No explicit when-not or alternative routing is provided, making usage guidance only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It usefully discloses a limitation ('Does not yet parse binary Stata/SPSS values') and the read-oriented nature of creating a summary, but it does not state whether the operation is purely read-only, how it handles malformed zips, or what warnings/next steps might be emitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence that front-loads the main purpose and then lists output contents in a clear, scannable sequence. Every clause adds information, and the limitation is stated compactly at the end without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description provides a reasonably complete picture: it names input type (export zip), the nature of the output (structural QC summary), and the categories included. It stops short of describing the exact return format or failure behaviors, but it gives enough context for an agent to understand what the tool produces.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides good descriptions for all three parameters (coverage 100%), so the description does not need to restate parameter meaning. The description adds no parameter-specific semantics beyond the schema, and under the 100% coverage baseline a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Create a first structural QC summary from a downloaded Survey Solutions export zip') and enumerates concrete output categories. It distinguishes itself from sibling QC/export tools by framing the output as a 'first structural' summary and explicitly noting it does not parse binary values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it — as an initial structural QC step on a downloaded export zip — and notes a limitation that rules out binary value parsing. However, it does not explicitly name alternative tools or state when another tool should be preferred, so the usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses that this is a live mutation ('no automatic idempotency key') and states permission requirements, which is critical for a write operation. It also advises reading the interview first, implying state dependencies. Some aspects like return value and visibility of the comment are not disclosed, but the major behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three tightly written sentences. The first sentence states the core action, the second gives the permission prerequisite, and the third delivers the risk warning and usage tip. No sentence is wasted, 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, no output schema, and a non-trivial parameter set, the description is adequate but not complete. It covers permissions, targeting, and idempotency, but it does not state what the API returns, the effect of the comment (e.g., where it becomes visible), or the meaning of the 'profile' parameter. Agents may still need to infer or investigate these details before confidently invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It clarifies that 'variable_name' and 'roster_vector' are the targeting mechanism and that the roster vector is optional, and mentions 'exact interview/variable/roster targeting'. However, the 'profile' parameter is left entirely unexplained, and 'comment' content is not described beyond the obvious, leaving a partial compensation for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Post') and resource ('question-level comment') with the addressing mechanism ('using a variable name and optional roster vector'). It is clear and concrete, but it does not explicitly distinguish itself from the closely named sibling 'comment_on_interview_question', relying on the tool name and targeting mechanism for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: permission requirements ('Requires fieldwork_write or admin_write permission'), a warning about the live mutation with no idempotency, and a best-practice instruction to read the interview first and use exact targeting. It does not explicitly state when to prefer this tool over the sibling comment tool, so it stops short of full alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It usefully discloses the critical non-mutating behavior ('does not write to Survey Solutions') and the dry-run nature, which is the most important safety trait. It does not detail what it returns or any validation behavior, but for a non-writing prep tool the key behavior is clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The primary purpose is stated first, followed by the essential non-write qualifier. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description must explain expected inputs and behavioral context. It fails to describe the expected structure of the issue objects, the role of profile, the meaning of default_action, or what a 'dry-run feedback batch' looks like upon return. An agent would still need to discover significant details from elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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, but it only vaguely implies the 'issues' parameter via 'structured issue list'. The 'profile' and 'default_action' parameters are not explained at all, and the shape of an 'issue' remains opaque given the schema just uses additionalProperties: true.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Convert') with a clear resource ('structured issue list' → 'dry-run feedback batch'). The phrase 'does not write to Survey Solutions' distinguishes it from the sibling apply_qc_feedback_batch without needing to open schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames this as a dry-run preparation step and explicitly states it does not write, which tells an agent when to use it. However, it does not explicitly name the alternative apply_qc_feedback_batch or state 'use this before applying changes', so it falls short of fully explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description supplies important behavioral facts: this is a write operation, requires fieldwork_write/admin_write, and question_id must follow the OpenAPI format with roster coordinates for roster questions. It does not mention return values or idempotency, but the disclosed permission and formatting details are the most material traits for a comment-posting call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences lead with the action, then the format caveat, then the permission requirement. Every sentence earns its place and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation with no output schema and no annotations, the description covers the action, target, required question_id format, roster edge case, and permissions. The main omissions are an explanation of the profile parameter and an explicit pointer to comment_on_interview_variable, but an agent has enough to construct a valid call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 adds real semantics for question_id by specifying the OpenAPI format and roster-coordinate handling, and comment/interview_id are inferable from their names, but the optional profile parameter is left unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The active verb 'Post' plus 'question-level comment' names both the action and the resource. By explicitly saying 'question-level,' it also separates this from the sibling comment_on_interview_variable tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context about the comment type and required permissions but never says when to prefer this tool over comment_on_interview_variable or other comment-related operations. The when-to-use guidance is only implied through the phrase 'question-level.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description discloses two important behavioral facts beyond the schema: admin_write authorization is required, and passwords should be treated as temporary setup secrets. It does not cover side effects such as immediate activation or return behavior, but the stated preconditions and password handling add real operational value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with no padding; the core action is front-loaded, followed by permission and security-relevant guidance. Every sentence adds information an agent needs before calling the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers the essential precondition and security note, but with eight parameters, no output schema, and no annotations it leaves several parameters unexplained and does not describe what a successful call returns. The role-to-supervisor relationship is left to the single schema hint rather than stated in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13%, and the description only adds meaning for the password parameter and partially for role. Username, email, full_name, profile, phone_number, and the supervisor dependency remain undocumented in both schema and description, so agents have to guess at several parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('supervisor or interviewer user'), and names the two valid role targets. It clearly differentiates this tool from the many get/list/archive user siblings by stating the creation action explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: create a new user of one of two roles, and clarifies the prerequisite admin_write permission. It does not enumerate exclusions or alternative tools, but the purpose statement makes the appropriate invocation context obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds a valuable safety guarantee: 'Secrets are never returned,' which tells the agent that sensitive data is intentionally excluded. The verb 'List' also implicitly signals a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. The core action and the key security caveat are both front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter list operation, the description is largely complete: it states what is listed and what is intentionally omitted. However, with no output schema, it does not specify the shape or fields of the returned profile list, which would further help an agent reason about the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty input schema, so parameter semantics are trivially satisfied. The description correctly implies that no arguments are needed to list profiles. The baseline of 4 applies because there are no parameters for the description to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clear resource ('configured Survey Solutions profiles'), making the tool's function immediately obvious. It also adds a meaningful qualifier ('Secrets are never returned') that sharpens the purpose. This distinguishes it adequately from profile-related siblings like get_active_profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance about when to use this tool versus alternatives such as get_active_profile, set_active_profile, or get_profile_permissions. While the phrase 'configured profiles' hints at enumeration, it does not state when listing is appropriate or when another profile tool should be chosen.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden; 'Explain' and 'suggest' convey a read-only diagnostic behavior, and the rest_request sentence adds a meaningful behavioral distinction across raw permission types. It does not cover edge cases like unknown tool names or profile-dependent results, but the main behavioral profile is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the core purpose is front-loaded and the rest_request nuance earns its place in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple diagnostic tool, the description covers selection, invocation context, and the needed special case for rest_request. It is not a 5 because there is no output schema and the optional 'profile' parameter remains unexplained, leaving a small gap in full call semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, so the description must compensate. It clarifies tool_name as the tool whose blocking is being explained and gives semantic grouping for method via 'GET, write, and DELETE raw permissions,' but it never explains the 'profile' parameter, which has no schema description either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('Explain whether a tool is blocked') tied to 'the current permission mode,' and adds what the output includes (CLI command or safer alternatives). The rest_request special case further distinguishes it from permission-related siblings like describe_permission_modes or generate_permission_change_command.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It is clear the tool is for checking block status and getting a safer path when a tool is blocked, so an agent can infer when to call it. It does not explicitly state when not to use it or name sibling alternatives, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing side effects. It clearly labels the operation as a 'Live mutation' and adds permission and confirmation requirements. It does not discuss reversibility or downstream effects, but the critical behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with no filler. The action, permissions, safety requirement, and workflow guidance are packed efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with five parameters and no output schema, this covers the essential prerequisites, safety check, and recommended workflow. It omits what happens on success or error and the optional profile parameter, but these are secondary to correctly invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 40%, so the description must compensate. It adds meaning for interview_id via 'exact interview ID confirmation' and for comment via 'include a clear comment', and responsible_id is already described in the schema. However, the profile parameter is not explained, and the imperative 'include a clear comment' sits awkwardly with comment being optional in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the specific action 'Reject an interview' with the actor 'as Headquarters', which clearly distinguishes it from the sibling reject_interview tool and the approve/unapprove variants. The verb, resource, and actor are all explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for when to use the tool: it requires fieldwork_write or admin_write permission, exact interview ID confirmation, a clear comment, and reading current status first. It does not explicitly name alternatives or state when not to use 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses that this is a 'live mutation,' specifies required permissions, and warns about confirmation and precondition checks. This is strong disclosure, though it does not describe side effects or reversibility beyond the state move.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with no filler. The action, permission requirement, safety warning, and precondition are all front-loaded and clearly separated. Every sentence contributes essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description covers the essential invocation context: purpose, permissions, confirmation requirement, and a precondition. It is slightly incomplete regarding optional parameters and behavior on mismatch, but the core agent decision path is well supported.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25%, so the description must compensate. It reinforces the critical confirm_interview_id requirement ('exact interview ID confirmation'), but it does not explain the interview_id, comment, or profile parameters. The description adds safety context but leaves several parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Move an HQ-approved interview out of HQ approved state.' This precisely defines the tool's state-transition purpose and differentiates it from related approval/rejection siblings by naming the specific state change.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives actionable guidance: requires specific permissions, requires exact interview ID confirmation, and says 'read current status first and use only on a known target case.' It does not explicitly name alternatives, but the preconditions and targeting advice make when-to-use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. 'Return canonical ... status names' clearly signals a read-only reference lookup with no side effects. It does not specify output formatting or whether the list is exhaustive, but for a zero-parameter, constant-style enumeration this is largely sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, information-dense sentence that front-loads the action and resource, then adds useful context about how the values are used. No redundant words or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool, the description adequately explains what the agent will get (canonical status names) and why that matters (filters and workflows). There is no output schema, so a fuller description of the exact return shape would help, but the description is complete enough for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is an empty object with zero parameters, so there are no parameter semantics to document. The baseline of 4 applies because the description is not required to compensate for any missing parameter explanations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Return' and a clear resource: canonical Survey Solutions interview status names. It also states the purpose ('used by export/status filters and fieldwork workflows'), which distinguishes this reference tool from data-returning siblings like list_interviews or summarize_fieldwork_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when this tool is relevant: when an agent needs canonical status names for export filters, status filters, or fieldwork workflows. It does not explicitly name alternatives or exclusion cases, but the use context is specific enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![survey-solutions-mcp MCP server](https://glama.ai/mcp/servers/lbruce-wq/survey-solutions-mcp/badges/card.svg)](https://glama.ai/mcp/servers/lbruce-wq/survey-solutions-mcp)

Score Badge

Copy to your README.md:

[![survey-solutions-mcp MCP server](https://glama.ai/mcp/servers/lbruce-wq/survey-solutions-mcp/badges/score.svg)](https://glama.ai/mcp/servers/lbruce-wq/survey-solutions-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lbruce-wq/survey-solutions-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server