ViaSocket is integration and AI infrastructure for developers. Connect 2,300+ apps, build and manage automated workflows, embed AI agents with persistent memory, and add authentication, organisations, and embedded integration UIs to your product through a single MCP server.
Scored across 15 tools
Most tools map to clearly distinct resources: plugin listing, action/trigger listing, action versions, auth versions, embed projects, org details. Two pairs need careful reading: call_any_api_of_viasocket vs call_any_read_api_of_viasocket (split only by HTTP method) and get_viasocket_api_docs vs search_viasocket_docs (browse an API tree vs natural-language search). The quickstart-viasocket-developer-hub entry is a skill rather than a real operation, which slightly muddies what the set is.
Nearly all names follow a verb_noun pattern (get_, list_, call_, report_, search_), which is predictable and readable. Deviations are minor but visible: the product name is appended inconsistently (call_any_api_of_viasocket, get_viasocket_api_docs, list_plugins) and the skill name uses hyphenated words instead of snake_case.
15 tools is at the top of the comfortable range but each covers a real sub-area of the Developer Hub (plugins, actions, triggers, versions, auth, embed SDK, docs, feedback). Nothing looks redundant enough to remove, though the two generic API callers plus two docs tools push it toward the heavy side.
The read/inspect side of the developer-hub lifecycle is well covered: org, plugins, actions/triggers, versions, auth, analytics, embed projects and secrets, plus docs lookup. Write operations (create plugin, publish action, create embed project) are only reachable through the generic call_any_api tool rather than dedicated helpers, so there are minor gaps but no dead ends.
Send a POST, PUT, PATCH or DELETE request to any viaSocket API endpoint for the user and return its response: every write (create, update, publish, delete). For GET requests use call_any_read_api_of_viasocket. Look the endpoint up with get_viasocket_api_docs first to get its URL, headers, query params and body, unless the skill or a dedicated tool on this server already gives them exactly. Load the quickstart-viasocket-developer-hub skill first: it explains which tool to use when. Pass the full url with path variables filled in, the headers the docs list, query params in query (not in the url) and the JSON body in body. For the auth header the docs name (Authorization, proxy_auth_token, x-api-key, ...), pass it with an empty value "": the signed-in user's token is filled in automatically. Never put a real or made-up token there; if the docs name no auth header, leave it out and the token is sent as Authorization. If the API needs the user to sign in, they're asked the first time. Only for the viaSocket endpoints documented on this server: it attaches the viaSocket sign-in, so never use it for Embarko (ship.embarko.ai) or any other service. Returns { status, ok, headers, data }: the HTTP status and the response body, including error details on failure.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Full endpoint URL with path variables replaced by real values, e.g. https://api.example.com/users/42. Put query params in `query`, not here. | |
| body | No | JSON request body, as the endpoint's docs show it. Leave it out when the endpoint takes no body. | |
| query | No | Query params as name/value pairs; an array sends the param once per item. Example: {"type": "flow", "bringflows": true} | |
| method | Yes | HTTP method from the endpoint's docs | |
| headers | Yes | Request headers as name/value pairs, as the docs list them. Give the auth header (Authorization, proxy_auth_token, x-api-key, ...) an empty value "" so the signed-in user's token is filled in; never put a token here yourself. Pass {} when the endpoint needs no headers. Example: {"proxy_auth_token": "", "Content-Type": "application/json"} |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive, non-idempotent, and open-world, but the description adds substantial behavioral context: auth headers must be passed with an empty value, the signed-in user's token is filled automatically, a sign-in prompt may appear on first use, and the response shape is { status, ok, headers, data } including error details. It also clarifies the tool attaches the viaSocket sign-in and must not be used for other services.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and the read/write distinction, then proceeds through docs lookup, skill loading, parameter passing, and auth behavior. It is appropriately detailed for a destructive open-world tool, but several sentences restate schema guidance already present in the input schema, making it longer than strictly necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—five parameters, required auth handling, destructive annotations, and no output schema—the description is complete. It explains how authentication is injected, how to pass headers and query parameters, how to obtain endpoint details, what the response contains, and which services the tool must not be used for.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already defines all five parameters in detail. The description reinforces key semantics—full URL with path variables filled in, query params in `query` rather than the URL, JSON body in `body`, and method restricted to POST/PUT/PATCH/DELETE—but much of this is already present in the schema. It adds marginal value with the fallback rule that if no auth header is named, the token is sent as Authorization.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: send POST, PUT, PATCH, or DELETE requests to any viaSocket API endpoint for the user. It explicitly distinguishes this write tool from its read-only sibling by naming call_any_read_api_of_viasocket and noting 'every write (create, update, publish, delete).' This is clear enough for an agent to distinguish it from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing rules: use call_any_read_api_of_viasocket for GET requests, look up the endpoint with get_viasocket_api_docs first, and load the quickstart-viasocket-developer-hub skill before proceeding. It also states a critical exclusion: only for viaSocket endpoints documented on this server, never Embarko or other services.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read from any viaSocket API endpoint with a GET request for the user and return its response. Use it once you know the exact endpoint: look it up with get_viasocket_api_docs first to get its URL, headers, query params and body, unless the skill or a dedicated tool on this server already gives them exactly. Load the quickstart-viasocket skill first: it explains which tool to use when. For POST, PUT, PATCH and DELETE use call_any_api_of_viasocket. Pass the full url with path variables filled in, the headers the docs list, and query params in query (not in the url). For the auth header the docs name (Authorization, proxy_auth_token, x-api-key, ...), pass it with an empty value "": the signed-in user's token is filled in automatically. Never put a real or made-up token there; if the docs name no auth header, leave it out and the token is sent as Authorization. If the API needs the user to sign in, they're asked the first time. Returns { status, ok, headers, data }: the HTTP status and the response body, including error details on failure.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Full endpoint URL with path variables replaced by real values, e.g. https://api.example.com/users/42. Put query params in `query`, not here. | |
| query | No | Query params as name/value pairs; an array sends the param once per item. Example: {"type": "flow", "bringflows": true} | |
| headers | Yes | Request headers as name/value pairs, as the docs list them. Give the auth header (Authorization, proxy_auth_token, x-api-key, ...) an empty value "" so the signed-in user's token is filled in; never put a token here yourself. Pass {} when the endpoint needs no headers. Example: {"proxy_auth_token": "", "Content-Type": "application/json"} |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description adds genuinely non-structured behavior: the empty-value auth-header convention with automatic token injection, the fallback to Authorization when no auth header is named, the first-time sign-in prompt, and the { status, ok, headers, data } return shape including error details on failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then prerequisites, then alternatives, then calling mechanics and return value – a sensible progression with little wasted framing. It is on the long side and repeats the empty-auth-header rule that the headers schema already states, which costs it the top mark.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic open-world HTTP proxy with no output schema, the description covers everything an agent needs: how to discover the endpoint, how to shape url/query/headers, how auth is handled, and what comes back. Nothing material is left to guesswork.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description still adds rules absent from the schema, notably that omitting the auth header causes the token to be sent as Authorization, plus the warning never to supply a real or fabricated token. It largely restates the url-vs-query split and the empty-value convention already in the schema, so it falls short of a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource+method: read any viaSocket API endpoint via GET and return its response. It explicitly carves out the sibling boundary by naming call_any_api_of_viasocket as the tool for POST/PUT/PATCH/DELETE, so the agent can pick correctly without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives ordered prerequisites (load quickstart-viasocket skill, look up the endpoint with get_viasocket_api_docs) and even states the exception where lookup can be skipped if a dedicated tool already provides the details. The alternative for write methods is named with the condition that selects it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the viaSocket organization (id and details) that the signed-in user's token belongs to. Read-only, no inputs. Call this first whenever you need the organization id (orgId) for other viaSocket Developer Hub calls such as List Plugins, Get Plugin or analytics, instead of asking the user for it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive and closed-world, so 'Read-only, no inputs' repeats structured data rather than adding to it. The genuinely additive part is that the org is derived from the caller's token, meaning the agent cannot request an arbitrary org — useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both load-bearing: the first defines the return value, the second defines when to call it. The primary action guidance is front-loaded with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must characterize the return value; it says 'id and details', which names the key field but leaves 'details' unspecified. For a simple no-input read tool this is close to sufficient, though an agent cannot predict the exact response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so the schema baseline is 4. The description correctly confirms 'no inputs', which is the only parameter-relevant statement available for a no-arg tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get the viaSocket organization (id and details)') plus the scoping mechanism (the signed-in user's token). It distinguishes itself from siblings by naming the downstream calls (List Plugins, Get Plugin, analytics) that need the value it returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit rule: 'Call this first whenever you need the organization id ... instead of asking the user for it.' That states both the triggering condition and the behavior to avoid, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get run counts, error counts and flow counts for every action and trigger version of a plugin (filter=getPluginDetails, identifier=, optional startTime and endTime dates).
| Name | Required | Description | Default |
|---|---|---|---|
| orgId | Yes | Your viaSocket organization id | |
| filter | No | Required (access check). Use getPluginDetails. e.g. getPluginDetails | |
| endTime | No | Optional end date. e.g. 2026-10-19 | |
| startTime | No | Optional start date. e.g. 2026-10-01 | |
| identifier | No | Required. Plugin id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds value the annotations do not: it discloses what the call returns (run/error/flow counts aggregated per action and trigger version), which matters because there is no output schema. It omits any note on auth scope beyond the 'access check' implied by filter, and nothing about volume or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with the payload description first and invocation details second. Every clause carries information; nothing is redundant padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With five parameters and no output schema, the description usefully characterizes the return shape (counts per action/trigger version) and flags the date window. The only gap is that it doesn't reconcile why filter and identifier are described as 'Required' in the schema while only orgId appears in the required array.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description only restates parameters already documented in the schema (filter, identifier, optional startTime/endTime) and adds no format, range, or default semantics beyond the schema's own examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get run counts, error counts and flow counts for every action and trigger version of a plugin'), with the exact grain of the data called out. No sibling tool (list_plugins, list_action_versions, get_org_details_by_token) computes per-version analytics, so an agent can route here without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical gives required invocation mechanics (filter=getPluginDetails, identifier=<pluginId>, optional dates), which implies the usage context but never states when to prefer this tool over list_plugins or list_action_versions. There are no exclusions or alternative-routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse the viaSocket API docs, one level at a time. Call it without arguments to get the top level: the modules and pages with a short description and the endpoints they hold. Call it with path set to a module's or page's link (or path) to get what is inside it; each listing links the next level. Call it with path set to an endpoint's link ending in ".openapi.yml" to get that endpoint as an OpenAPI file: method, url, headers, query params, path variables, a request body example and sample responses. Fetch only the level you need.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | A link from a listing, exactly as given (e.g. "https://docs.example.com/sms/llms.txt" or ".../sms/send-sms.openapi.yml"), or just the path ("sms", "sms/send-sms.openapi.yml"). Leave it out for the top level. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive) so that burden is lifted, and the description still invests heavily in describing what each call returns: module/page listings with short descriptions and held endpoints, and a full OpenAPI payload with method, url, headers, query params, path variables, body example and sample responses. With no output schema present, this return-shape disclosure is exactly the added value needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the traversal model and then each invocation mode in sequence. No filler; the final sentence ('Fetch only the level you need') is a genuine efficiency instruction rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A single optional parameter, no output schema, and rich annotations, yet the description still covers all three request modes and the corresponding return contents. Nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already explains the accepted forms, so the baseline is 3. The description earns above baseline by tying the parameter to the three distinct behaviors (omit = top level, module/page link = listing, '.openapi.yml' = endpoint spec), which is routing meaning rather than restatement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Browse') and resource ('viaSocket API docs') plus the traversal model ('one level at a time'), which is exactly the property that separates it from a flat search tool. An agent can predict the response shape at each level without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit invocation modes: no arguments for the top level, `path` for a module/page, `path` ending in '.openapi.yml' for an endpoint spec. It also advises 'Fetch only the level you need.' It stops short of naming siblings such as search_viasocket_docs or saying when NOT to browse (e.g., when you already know what you want and should search instead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets the viaSocket organization's embed signing secret (VIASOCKET_EMBED_SECRET) into the developer's .env encrypted, so you never see it. Use it in SDK setup. Get orgId with get_org_details_by_token first. Before calling, run docstar-cli key request in the project folder and pass its publicKey; then run the save command this tool returns, then its emit command (the developer can choose another .env file). Never ask for, print or repeat the secret.
| Name | Required | Description | Default |
|---|---|---|---|
| orgId | Yes | The orgId the key is created for | |
| publicKey | Yes | The publicKey printed by `docstar-cli key request`, exactly as printed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=false and openWorldHint=true already given, the description adds real context: the secret is written encrypted and never surfaced, a shell command must precede the call, and the returned commands must be executed in sequence. It does not address whether repeated calls create or rotate a key (relevant given idempotentHint=false) or what happens to an existing secret, which is the main remaining gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and the never-print constraint lead, followed by the prerequisite chain in execution order. Every clause maps to an action the agent must take; there is no filler despite the density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema, the description covers prerequisites, the call sequence, the return shape in functional terms (commands to run), and a security constraint. It stops short of error conditions or post-call verification steps the agent might need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, yet the description still adds provenance: publicKey must come verbatim from `docstar-cli key request` and orgId from get_org_details_by_token. That is genuine meaning beyond the schema strings, though it doesn't cover format/validation of either value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb and resource ('Gets the viaSocket organization's embed signing secret') and scopes the outcome to writing an encrypted .env entry. It is clearly distinct from siblings like get_org_details_by_token, though the parenthetical variable name and side-effect framing make it slightly denser than a one-line purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says the context ('Use it in SDK setup'), names the prerequisite tool ('Get orgId with get_org_details_by_token first'), and lays out the ordered steps: run `docstar-cli key request`, call this tool with the publicKey, then run the returned `save` and `emit` commands. It even notes the developer may target a different .env file, leaving almost nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a plugin's actions and triggers (filter=getAllActions, identifier=), or get one (filter=getActionDetails, identifier=). Use it to find an actionId.
| Name | Required | Description | Default |
|---|---|---|---|
| orgId | Yes | Your viaSocket organization id | |
| fields | No | Optional comma-separated columns, e.g. rowid,name,type,status | |
| filter | No | Required. getAllActions (by plugin) or getActionDetails (one action by rowid). e.g. getAllActions | |
| identifier | No | Required. Plugin id for getAllActions; action id for getActionDetails |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish readOnly, idempotent, openWorld and non-destructive behavior, so the safety profile is fully covered. The description contributes the two-mode behavior (list by plugin versus fetch one by id), but says nothing about result size, pagination, or whether triggers are included in each mode. Useful, but thin beyond what the annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with the listing mode stated first and the detail mode second, plus the motivating use case at the end. Every clause carries information and nothing is padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with full schema annotations and no output schema, the description covers both modes and the downstream purpose of the returned ids. It could mention what fields come back or whether triggers and actions are returned together, but nothing that blocks a correct call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already documents filter values, identifier mapping, and the optional fields column list. The description's parenthetical 'filter=getAllActions, identifier=<pluginId>' essentially restates the schema rather than adding new examples or constraints, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('List a plugin's actions and triggers') and also covers the single-item detail mode, so the agent knows exactly what is returned. It does not differentiate against the closest sibling, list_action_versions, which could look similar to an agent scanning a tool list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It supplies a concrete use case ('Use it to find an actionId'), which gives the agent a clear trigger for calling it. It stops short of stating exclusions or naming alternatives such as list_action_versions for versioned data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all versions of an action or trigger (filter=getActionVersions, identifier=), with code, inputs, authid, status and verification status. Use fields to keep the response small.
| Name | Required | Description | Default |
|---|---|---|---|
| orgId | Yes | Your viaSocket organization id | |
| fields | No | Optional comma-separated columns, e.g. rowid,versionid,status,verificationstatus | |
| filter | No | Required. Must be getActionVersions. e.g. getActionVersions | |
| identifier | No | Required. Action id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower; the description adds real value by enumerating what is returned (code, inputs, authid, status, verification status) and by flagging response size as a concern with a mitigation. It stops short of describing pagination or the cost of pulling full code payloads.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the core purpose front-loaded and the optimization hint trailing. Every clause carries information the agent can act on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With four simple flat parameters, full schema coverage, and no output schema, the description covers purpose, invocation contract, and returned fields. It could be slightly more complete about whether results are paginated or how many versions are typically returned, but an agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents orgId, fields, filter, and identifier. The description reinforces the filter/identifier contract and the fields trimming tip but adds no syntax or format detail beyond what the schema states; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('List all versions of an action or trigger') and even discloses the underlying API filter and identifier form. It is clearly distinguishable from siblings like list_actions_and_triggers or list_auth_versions by resource, though it never names an alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the parenthetical shows the required filter/identifier pairing needed to invoke it correctly, and the final sentence advises using fields for small responses. There is no explicit statement of when to choose this over list_auth_versions or list_actions_and_triggers, nor any prerequisite or exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a plugin's authentication versions (filter=getAuthDetails, identifier=) to find an authid. Responses include decrypted client secrets: never show them to the user.
| Name | Required | Description | Default |
|---|---|---|---|
| orgId | Yes | Your viaSocket organization id | |
| fields | No | Optional comma-separated columns | |
| filter | No | Required. getAuthDetails (all of a plugin's auth versions) or updateAuthDetails (one auth version by rowid). e.g. getAuthDetails | |
| identifier | No | Required. Plugin id for getAuthDetails; auth version rowid for updateAuthDetails |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds genuinely non-obvious behavior: responses contain decrypted client secrets that must never be shown to the user. That is real value beyond structured fields, though pagination/response-shape behavior is unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence with the operation, the invocation parameters, the goal, and the security warning, all front-loaded with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-param, no-output-schema read tool with rich annotations, the description covers purpose, invocation mode and the critical secret-handling caveat. It leaves the 'fields' parameter and result shape unexplained, which keeps it short of a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both filter and identifier are fully documented in the schema, setting the baseline at 3. The description only restates one filter value and the pluginId binding, adding no syntax or usage nuance beyond what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List a plugin's authentication versions') and pairs the concrete filter/identifier values, so an agent knows exactly what it returns. It implicitly differentiates from list_action_versions by naming auth versions, but never explicitly contrasts with that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'to find an authid' gives an implied use case, and the filter hint narrows the mode of invocation. However, there is no explicit when-not guidance and no mention of when to prefer this over siblings like list_plugins or call_any_read_api_of_viasocket.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List an organization's embed projects (type=embed) for viaSocket SDK setup. Each data.projects[].id is a project_id (VIASOCKET_PROJECT_ID). Reuse an existing embed: one embed serves a whole product. Only if there is none, create one with the Create Embed Project endpoint (via call_any_api) after the developer confirms.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Required. `embed` for SDK projects (`flow` and `default` are the workspace's own automation projects). e.g. embed | |
| orgId | Yes | Organization id from Find Organizations or Get Org Details By Token | |
| bringflows | No | Optional. true also returns the flows of each project. e.g. false |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful context beyond them: data.projects[].id maps to a project_id used as VIASOCKET_PROJECT_ID, and creation should only happen after developer confirmation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded, compact, and every sentence carries useful selection or workflow information. There is no redundant restatement of the title or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no output schema, the description covers the key returned identifier and the reuse/create decision. It does not detail the optional bringflows parameter or full response shape, but the schema covers parameters adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains orgId, type, and bringflows. The description reinforces type=embed and organization context but adds no further parameter syntax or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: listing an organization's embed projects for viaSocket SDK setup. It also distinguishes the create fallback by naming the Create Embed Project endpoint via call_any_api.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to reuse an existing embed because one embed serves a whole product, and only create one if none exists, after developer confirmation. This gives clear when-to-use and alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every viaSocket Developer Hub plugin (app) the user's organization owns. Send filter=getAllPlugins and identifier equal to the orgId in the path. Start here to find a pluginId (rowid).
| Name | Required | Description | Default |
|---|---|---|---|
| orgId | Yes | Your viaSocket organization id | |
| fields | No | Optional comma-separated list of columns to return, e.g. rowid,name,status,iconurl | |
| filter | No | Required. Must be getAllPlugins. e.g. getAllPlugins | |
| identifier | No | Required. Your orgId (same as the path) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds that this is a starting point that yields a rowid, but the rest largely restates how to fill parameters rather than adding deeper behavioral context (e.g. pagination or result shape).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the what and scope, then the how and the payoff (pluginId). No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with rich annotations, the definition covers what it returns (rowid) and how to call it. Without an output schema, it could say slightly more about result shape, but it is essentially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all four parameters are already documented in the schema. The description only restates filter=getAllPlugins and identifier=orgId, adding little beyond what the schema says. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) plus resource (viaSocket Developer Hub plugins/apps) and scope (org owns), and clarifies the output is a pluginId/rowid. An agent can tell this apart from sibling tools like list_actions_and_triggers or get_plugin_analytics without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Start here to find a pluginId (rowid)' gives clear entry-point context and the downstream purpose of the call. It does not explicitly name exclusions or alternative siblings, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quickstart for viaSocket: build and manage your viaSocket plugins (apps) in the Developer Hub (auth, actions, triggers, versions, reusable components, debugging), set up the viaSocket SDK, and build automations (flows) for the user: find apps, connect accounts, create flows, set triggers and write steps. Routes plug work (plug, action, connection) through the plug skills index, SDK integration through the viaSocket skill, and Embarko deploy through Embarko's quickstart. Load this before any viaSocket task. Call this to load the full instructions for this skill before doing the task.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description is consistent with that. Beyond the annotations, it discloses the key behavioral fact an agent needs: this returns full instruction text rather than performing an action, and it must be called before other viaSocket work. No mention of payload size or token cost, which for an instruction-loading tool would be useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded and the closing sentence is the most actionable, but the first sentence is a long run-on with stacked parentheticals ('auth, actions, triggers, versions, reusable components, debugging') that reads as scope padding. The middle routing sentence references external skills the agent cannot resolve from this context, adding length without clear payoff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, no output schema and a safe read-only annotation profile, the description covers what the agent needs: what the tool returns, that it is a prerequisite, and where to go for adjacent work. Minor gap is that it never states the shape or volume of the returned instructions, which matters for a skill-loading tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter semantics to explain; the schema is empty and consistent with the description. Baseline 4 applies for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the domain (viaSocket Developer Hub, SDK, automations) and, in the final sentence, the actual action: 'load the full instructions for this skill before doing the task.' It distinguishes itself from the API-calling siblings by framing itself as a prerequisite instruction loader, though the opening sentence describes the skill's subject matter rather than the tool's operation, which could momentarily read as if the tool itself builds plugins and flows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit trigger: 'Load this before any viaSocket task' and 'Call this to load the full instructions for this skill before doing the task.' It also routes specific sub-work (plug work, SDK integration, Embarko deploy) to other skills, giving an alternative-selection rule. The routing sentence is somewhat opaque about what the agent should actually do, and the named skills are not in the visible sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report a problem to viaSocket while building with it: an error, a confusion, wrong docs or skills, a user correction, or a missing capability. Problems only, never success; no need to ask the user; a failed report never stops the task. Plugs: fix or extend the user's own plugs (the ones in list_plugins) yourself, and build a plug for an app that has none. A plug used in flows but not in list_plugins is viaSocket's: never edit it, report it here (refs.pluginId, refs.actionId; a missing action, trigger or field is kind missing_capability, with exactly what is needed and why). Body: source (sdk | http_api | plug | action | trigger | connection | skill | other), kind (error | confusion | missing_capability | wrong_instructions | user_correction) and feedback (what happened, in plain words), plus optional severity, stage, intent, attempted, expected, actual, error, refs, env and retries. Never include secrets, tokens or script_id. The org and user come from the sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | e.g. {"sdkVersion":"0.7.0","framework":"nextjs","language":"typescript","client":"claude-code"} | |
| kind | No | e.g. error | |
| refs | No | e.g. {"app":"slack","pluginId":"rowslack123","actionId":"rowsendmsg01","requestId":"req_abc"} | |
| error | No | e.g. {"status":500,"code":"INTERNAL","message":"failed"} | |
| stage | No | e.g. actions_and_events | |
| actual | No | e.g. 500 INTERNAL | |
| intent | No | e.g. Post to a Slack channel when an order is created | |
| source | No | e.g. action | |
| retries | No | e.g. 2 | |
| expected | No | e.g. Message posted | |
| feedback | No | e.g. Slack Send Message returns 500 on valid input; same call worked yesterday | |
| severity | No | e.g. degraded | |
| attempted | No | e.g. Ran Send Message with channel and text from the document's sample |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare this is a non-destructive write; the description adds the substantive behavior: org and user are derived from the sign-in (no auth params needed), a failed submit is non-blocking, and secrets/tokens/script_id must be excluded. That is context an agent could not recover from the schema or hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then guardrails, then the plug edge case, then body fields — a sensible order. It is dense and occasionally wordy ("with exactly what is needed and why") and contains a small wording slip ("Report a problem to viaSocket"), but no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter, nested-object tool with no output schema, the description accounts for every body field including the optional ones and explains where identity comes from. The only gap is that it says nothing about what a successful submission returns, which is minor since no output schema is published.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds the closed value sets for source and kind that the schema leaves as free strings with no enums, plus the required trio (source, kind, feedback). It further specifies refs.pluginId/refs.actionId for viaSocket-owned plugs and classifies a missing action/trigger/field as kind=missing_capability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Report a problem to viaSocket") and enumerates the accepted problem classes (error, confusion, wrong docs/skills, user correction, missing capability), which sharply bounds what belongs here. It does not name the nearest sibling (report_published), so the agent must infer that the success/publish path lives elsewhere.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use (problems only, never success), when-not (do not ask the user first), and failure semantics (a failed report never stops the task). It also routes a specific ambiguous case: a plug used in flows but absent from list_plugins is viaSocket's, so never edit it — report it here instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call once right after you publish something on the user's own plug (one in list_plugins): a new plug, or a new action, trigger, version or connection on it. viaSocket then reviews the published plug and may add missing actions or triggers. Body: pluginId (the plug rowid, required), published (new_plug | new_action | new_trigger | new_version | connection), plus optional app (the app's name), actionIds (rowids of the actions or triggers just published) and note (plain words, never secrets). No need to ask the user; a failed call never stops the task. The org and user come from the sign-in. Not for problems: use report_feedback for those.
| Name | Required | Description | Default |
|---|---|---|---|
| app | No | e.g. Tally | |
| note | No | e.g. Published privately with 4 actions and 1 trigger; OAuth 2.0 connection | |
| pluginId | No | e.g. rowtally12345 | |
| actionIds | No | e.g. ["rowaction1234","rowtrigger567"] | |
| published | No | e.g. new_plug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the write/non-destructive annotations, it discloses the downstream consequence (viaSocket reviews the plug and may add missing actions or triggers), the failure semantics ('a failed call never stops the task'), and where identity comes from (the sign-in). These are non-obvious traits an agent could not infer from readOnlyHint/destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the call condition, then body fields, then caveats and the exclusion. Dense but every clause carries information; the parenthetical asides are justified rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers when to call, what to send, failure tolerance, auth source and the alternative tool, which is nearly everything needed for a 5-parameter write with no output schema. The only soft spot is that it never says what the call returns, though the 'failed call never stops the task' note makes inspection unnecessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it enumerates the published values (new_plug | new_action | new_trigger | new_version | connection) that the schema only hints at via an example, ties actionIds to 'just published', and constrains note to 'plain words, never secrets'. It also asserts pluginId is required even though the schema lists no required fields, which is a helpful correction but reveals a slight schema/description mismatch.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (report) and event (a publish on the user's own plug), enumerates the publish types, and names the sibling it is not (report_feedback). An agent can distinguish it from list_plugins and report_feedback without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger ('Call once right after you publish'), tells the agent not to ask the user, reassures that failure is non-blocking, and excludes the problem-reporting case by routing to report_feedback. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the viaSocket documentation with a natural-language question. Returns the most relevant passages with their page URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to look for, e.g. "how do I send a WhatsApp template message" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the description needn't restate safety. It adds genuine value by disclosing the return shape (relevant passages annotated with page URLs), which matters because there is 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the search action and query mode front-loaded and the return behavior second. Nothing could be cut without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool this covers what it does and what it returns, and annotations cover the safety profile. Minor gaps: result count, ranking behavior, and whether results are scoped to a specific product area are unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single required parameter is documented with an example in the schema itself. The description's 'natural-language question' phrasing adds a small hint about query formulation, but nothing beyond that — baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (search) and resource (viaSocket documentation) plus the query mode (natural-language question). It is clearly distinct from retrieval-style siblings like get_viasocket_api_docs, but it never names them to make the distinction explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the phrase 'natural-language question,' which suggests conceptual/how-to lookups rather than endpoint reference lookups. However, no when-to-use or when-not-to-use guidance is given against get_viasocket_api_docs or quickstart-viasocket-developer-hub, which an agent could easily confuse with this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
call_any_api_of_viasocketcall_any_read_api_of_viasocketget_org_details_by_tokenget_plugin_analyticsget_viasocket_api_docsget_viasocket_embed_secretlist_action_versionslist_actions_and_triggerslist_auth_versionslist_embed_projectslist_pluginsquickstart-viasocket-developer-hubreport_feedbackreport_publishedsearch_viasocket_docs
Add one secure layer between your agents and this server.