Tool input schema

What it means

A tool input schema is a JSON Schema document that describes exactly what arguments a tool accepts. It lists each argument's name and type, and for each one it can set a range, an enum of allowed values, a pattern the value must match, and whether the argument is required. The schema is the contract between the caller and the tool: anything the schema does not declare is not part of the tool's interface.

In MCP the schema is published under the key inputSchema, so a client can read a tool's argument list before it ever attempts a call. That makes the schema useful in two directions. A developer can read it to learn the shape of a call without guessing, and a server can use the same document to reject arguments that do not conform before any work happens.

How it works

A schema is a normal JSON Schema object. The properties key maps each argument name to its own constraints, a required array names the arguments that must be present, and keywords such as type, minimum, maximum, enum and pattern narrow the accepted values. Setting additionalProperties to false closes the object, so an argument that is not in properties is not accepted at all.

Validation runs in a fixed order: the argument object is checked against the schema first, and only then is the tool invoked. A failure at that stage is a calling error, not a tool error, so it comes back as an error response rather than a partial result. HTTP status codes follow the usual meaning here: a 400 means the request itself was malformed or its arguments failed validation, and the caller should fix the request before retrying.

How OneLifeVibe uses it

Every OneLifeVibe tool publishes its inputSchema. Connectors get the schemas from tools/list over the remote MCP server. Developers calling the REST API get the same schemas from GET /api/platform/v1/tools, so you can enumerate the arguments for each tool before writing a request.

All OneLifeVibe schemas set additionalProperties: false. Arguments are validated before anything is called. An undeclared argument, a missing required one, a wrong type, or a value outside its range, enum or pattern is refused, and the Platform API returns 400 invalid_arguments. Only declared arguments are forwarded to the website, so a field your request carries that the schema does not list never reaches the site's code.

That behavior shapes how you should debug. If a call comes back with invalid_arguments, compare your argument object against the published schema key by key instead of retrying the same payload. Check the argument name spelling, the type, and any range, enum or pattern constraint on the value that failed.

Common mistakes

The most common mistake is sending extra fields, for example a value copied from another tool or a client-side identifier added for bookkeeping. Because OneLifeVibe schemas set additionalProperties: false, those fields are refused as undeclared rather than being ignored. Trim the object to the declared arguments.

A second mistake is treating a validation failure as a transient error and retrying unchanged. A 400 invalid_arguments will keep failing until the arguments match the schema, so fix the request first. Also watch type coercion: a number sent as a string, or a value outside an enum, fails even when it looks close to correct.