The server provides 41 tools with consistent naming patterns (verb_noun), moderate descriptions, and basic parameter schemas. However, there are significant gaps: (1) parameter descriptions lack depth and concrete constraints (e.g., enum values for 'type' and 'role' fields are mentioned in descriptions but not formalized in schemas), (2) output schemas are entirely undocumented, no response structures are defined in the source, (3) error handling guidance is minimal, (4) many parameters lack explicit type definitions in JSON Schema (e.g., 'variables' in create_user_environment is typed as 'array' with no item type specified), and (5) some descriptions are generic and don't explain WHEN to use a tool vs. similar alternatives. The naming is solid (all 41 tools follow verb_noun convention), but the definition completeness falls short of production-grade quality. Composition is good, tools are single-purpose and chainable.
Output schemas are completely undocumented. No return types are specified for any of the 41 tools, making it impossible for LLMs to know what fields to expect or how to chain downstream tool calls. This violates the 'Document the output schema' pattern and forces agents to guess at response structure.
Document output schemas for all 41 tools. For each tool, add a 'returns' section in the description or create a formal JSON Schema response structure. Example: 'Returns: {id: string, title: string, type: string, createdAt: ISO8601 string, items: []}'.
Formalize enum constraints in JSON Schema. Convert prose enums like 'Collection type (REST, GraphQL, GRPC, WEBSOCKET)' to proper 'enum' fields. Example: 'type': {'type': 'string', 'enum': ['REST', 'GraphQL', 'GRPC', 'WEBSOCKET']}.
Add explicit constraints to numeric and string parameters. Example: 'limit': {'type': 'number', 'description': 'Maximum results per page (1-100, default 20)', 'minimum': 1, 'maximum': 100}.
Clarify vague parameters like 'data' and 'jsonString'. For 'data' in collection creation, document the expected structure: 'Optional metadata object (e.g., {description: string, tags: [string]})'.
Add error handling guidance to destructive tools. Example for delete_user_collection: 'Error: 404 if collection not found. 403 if no permission. 400 if collection contains items that cannot be deleted. Provide user-friendly error messages guiding recovery.'
Expand descriptions for 'duplicate' and 'move' tools to clarify intent. Example: 'Duplicate a collection: creates a copy (with new ID, same structure/requests). Use when you need a variant of an existing template. Alternative: create_user_collection to build from scratch.'
Score history
Overall score trend
First recorded score · v2 rubric
52/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-23
D
52
2026-07-28+
v2
delete_user_collectiondestructiveauth50/100
Delete a user collection
delete_user_environmentdestructiveauth50/100
Delete a user environment
duplicate_team_collectionwriteauth50/100
Duplicate a team collection (standard mode)
duplicate_user_collectionwriteauth50/100
Duplicate a user collection (standard mode)
execute_requestread onlyauth50/100
Execute an HTTP request (request execution)
export_team_collectionread onlyauth50/100
Export team collection as JSON
export_user_collectionread onlyauth50/100
Export user collection(s) as JSON
generate_coderead onlyauth50/100
Generate code snippets for HTTP requests (code generation)
get_team_collectionread onlyauth50/100
Get a specific team collection by ID
get_team_inforead onlyauth50/100
Get detailed information about a specific team (read-only team management)
get_user_collectionread onlyauth50/100
Get a specific user collection by ID
import_team_collectionwriteauth50/100
Import team collection from JSON
import_user_collectionwriteauth50/100
Import user collection(s) from JSON
invite_team_memberwriteauth50/100
Invite a user to a team (team management write)
leave_teamreversibleauth50/100
Leave a team (team management write)
list_team_collectionsread onlyauth50/100
List team collections
list_team_environmentsread onlyauth50/100
List team environments
list_teamsread onlyauth50/100
List all teams the user is a member of (read-only team management)
list_user_collectionsread onlyauth50/100
List user collections with optional type filtering, cursor pagination, and limit
list_user_environmentsread onlyauth50/100
List all user environments
move_team_collectionwriteauth50/100
Move a team collection to a different parent (standard mode)
move_user_collectionwriteauth50/100
Move a user collection to a different parent (standard mode)
reauthwriteauth50/100
Force a fresh device-login (QoL). ALWAYS clears caches + abandons any in-flight flow via reauthenticate() — the documented cleanup. A configured HOPPSCOTCH_ACCESS_TOKEN cannot be replaced, so that branch reports that the static token stays in use instead of claiming a fresh session.
remove_team_memberreversibleauth50/100
Remove a member from a team (team management write)
rename_teamwriteauth50/100
Rename an existing team (team management write)
revoke_team_invitationreversibleauth50/100
Revoke a pending team invitation (team management write)
search_team_requestsread onlyauth50/100
Search team requests (standard mode)
update_team_collectionwriteauth50/100
Update an existing team collection
update_team_environmentwriteauth50/100
Update an existing team environment
update_team_member_rolewriteauth50/100
Update a team member's role (team management write)
update_user_collectionwriteauth50/100
Update an existing user collection
update_user_environmentwriteauth50/100
Update an existing user environment
validate_responseread onlyauth50/100
Validate an HTTP response against criteria (request execution)
Enum constraints are mentioned in descriptions but not formalized in JSON Schema. The 'type' parameter (REST, GraphQL, GRPC, WEBSOCKET) appears in 18+ tools but has no 'enum' field in the schema. Similarly, 'role' parameter (OWNER, EDITOR, VIEWER) in team management tools lacks enum definitions. LLMs cannot reliably parse prose enums and often hallucinate invalid values. Moving these to formal 'enum' fields in the schema is critical.
Parameter 'variables' in create_user_environment, update_user_environment, create_team_environment, and update_team_environment is typed as 'array' with no item schema specified. The structure of array elements is completely unknown to LLMs. Should define items as objects with 'key' (string) and 'value' (string) properties at minimum.
Parameters like 'data' and 'jsonString' are typed as 'object' and 'string' respectively with minimal description. 'data' in collection creation/update tools lacks structure documentation (what fields are allowed?). 'jsonString' in import tools provides no guidance on expected JSON structure. This forces LLMs to guess or hallucinate valid payloads.
No error handling guidance provided. Tools that perform destructive operations (delete_user_collection, delete_team, etc.) do not document what errors they might return or how LLMs should interpret failure states. Tools that depend on user authentication (reauth, all API calls) lack recovery guidance if credentials fail.
Descriptions for duplicate_user_collection, duplicate_team_collection, move_user_collection, move_team_collection are vague (50-58 chars). They mention '(standard mode)' but never explain what that means or when to use these vs. alternatives. What's the difference between duplicating and creating? When would an LLM choose one over the other?
Parameter descriptions lack concrete examples and constraints. For instance, 'cursor' in list_user_collections is described as 'Pagination cursor' with no guidance on format (is it opaque? a timestamp? an offset?). 'limit' and 'page_size' equivalents lack min/max bounds. LLMs cannot reliably infer valid input ranges without explicit constraints.
Parameter 'parentCollectionId' in collection tools is described as 'Optional parent collection ID' but lacks documentation on what happens if the ID is invalid, or how to move/nest collections properly. Similarly, 'teamId' in many team tools says '(optional if HOPPSCOTCH_DEFAULT_TEAM_ID is set)' but doesn't explain the fallback logic clearly.
Descriptions for execute_request and validate_response are generic (60 and 55 chars). execute_request doesn't clarify what 'environmentId' does for variable substitution or how to format headers/body. validate_response doesn't explain when to use it, is it for test assertions? This forces LLMs to guess intent.
No documentation of parameter dependencies or mutual exclusivity. For example, if export_user_collection can export a single collection (collectionId provided) OR all collections (collectionId omitted), this dependency should be explicit in the parameter descriptions to prevent LLM confusion.
export_user_collectionexport_team_collection
Document pagination behavior. For list_* tools, clarify whether cursor is opaque or time-based, and what total count or next_cursor fields are returned. Example: 'Returns: {collections: [], cursor: string (null if last page), total: number}'.
Specify parameter dependencies explicitly. If parentCollectionId can be null, document this: 'parentCollectionId (optional, null to place at root level)'.
Document variable substitution for execute_request. Add example: 'environmentId: Optional environment ID. If provided, request substitutes {{varName}} placeholders with environment variables. Example: url="https://{{baseUrl}}/api/users" with environmentId containing baseUrl="https://api.example.com"'.
Clarify optional parameter semantics for teamId. Document: 'teamId: Optional. If omitted, uses HOPPSCOTCH_DEFAULT_TEAM_ID from server config. If set, overrides default. Must be a valid team ID the user has access to.'
Add WHEN to use each tool. For search_team_requests vs list_team_collections, add guidance: 'Use search_team_requests to find specific API requests by name/URL. Use list_team_collections to discover collection structure. These are complementary discovery tools.'
Include chaining IDs in response descriptions. Document that create_user_collection returns 'collectionId' so agents can immediately call add_request_to_collection(collectionId, ...).
Validate input types early. Add 'Invalid input' error guidance: 'If role is not OWNER|EDITOR|VIEWER, return: "Invalid role '{value}'. Must be one of: OWNER, EDITOR, VIEWER."'
Document the reauth flow. Clarify whether reauth clears ALL caches or just authentication tokens, and what happens to in-flight requests (the description hints at reauthenticate() cleanup, but the mechanism is unclear).