MCP Tool Schemas: Catch Invalid Arguments Before They Cost Time

A content request can be clear to a person and invalid to a tool. “Give me six caption options” is understandable, but a schema may allow only three, four, or five. If the assistant treats the instruction as permission to invent an argument, the request fails before the useful work begins.

JSON Schema describes the shape and constraints of tool inputs and, where provided, outputs. Reading those constraints is a practical way to reduce avoidable retries. It also helps distinguish a bad request from an authorization problem, a generation failure, or an unavailable service.

Understand the contract before constructing arguments

The MCP tools specification defines inputSchema and optional outputSchema fields for tools. The schema is more precise than a conversational description because it states types, required properties, and allowed structures.

The JSON Schema object guide explains properties, required fields, and additionalProperties. These concepts answer basic integration questions: which fields can appear, which must appear, and whether the server accepts fields the schema does not list.

A property being documented does not automatically make it required. Conversely, a field that looks obvious to a human may still need to be explicitly present. Read the required list instead of inferring it from an example payload or the order of fields in the reference.

Caroush's schema catalog provides the actual contracts. Use the current version when preparing an AI content request, especially if a copied example came from an older tool definition.

Check types and allowed values first

A number, a numeric-looking string, and a missing value are different inputs. If an object identifier must be an integer, quoting it as text can violate the contract. If an array must contain unique integers, repeated identifiers can fail even when each item is valid individually.

Enumerated values also matter. Caroush's documented generate_captions tool accepts a variant_count from a specific set: three, four, or five. A request for six variants needs an editorial adjustment or a separately justified workflow, not an invented unsupported value.

Do not solve every limit by splitting the task into more paid requests automatically. Confirm that additional calls are wanted and account for credits or quotas where applicable. The schema defines what a single request accepts; it does not authorize unbounded repetition to satisfy a larger natural-language request.

For a caption review, three strong alternatives may be more useful than a larger set of weak variations. A caption call-to-action guide can help evaluate quality after the valid request completes.

Missing, empty, and null are not interchangeable

An optional field can sometimes be omitted entirely. An empty string is a provided string with no content. A null value has its own type. The schema determines which forms are accepted, and the application's business rules determine how an accepted value is interpreted.

This distinction is especially relevant when an assistant fills every visible field “for completeness.” Adding an empty or null value can change behavior or make the request invalid. If the field is optional and the task does not require it, omission may be the correct representation under the documented contract.

Caroush's create_text_post requires a caption and an idempotency key. Its optional status accepts documented values. The assistant should not add an invented publish flag to express urgency or set an unsupported status to make the object appear further along.

A draft is still a draft regardless of how strongly the prompt requests publication. Use the separate documented operation and approval flow when the task reaches scheduling or publication.

Existing-object identifiers carry ownership constraints

Schema validation can confirm that an asset ID is an integer within a permitted range. It cannot by itself establish that the asset belongs to the authorized workspace or is suitable for the intended destination. The service must apply those business checks.

Caroush's create_image_post references existing owned media IDs, with a documented limit and ordering. A valid-looking integer from another workspace is not an acceptable substitute. Nor does a field named asset_ids imply that a URL can be supplied instead.

For a carousel workflow, the order of media references can affect the story. Validate the array structurally, then inspect the actual assets and their order as an editorial check. Technical validity and content correctness are separate acceptance criteria.

When ownership fails, retrieve the correct permitted objects through documented operations. Do not guess neighboring identifiers or broaden access until one happens to work. An ownership error is a boundary to respect and diagnose, not a puzzle to solve by enumeration.

Validate the response as carefully as the request

A successful call can return structured information about a draft, a queued job, or an approval requirement. The output schema helps the client interpret those fields consistently. A missing final object in a queued response should not be “filled in” by the assistant's imagination.

Caroush documents request status values and, for relevant operations, operation identifiers or approval URLs. Read the returned state before deciding what the user should do next. A response marked approval_required does not support a statement that publication is complete.

Similarly, a tool-level error may be present inside an otherwise successful protocol response. The client must not rely only on transport success. Inspect the documented error structure and keep the original request identity when following a failed or uncertain mutation.

For maintainers, output validation can catch integration drift. If a client expects a field that the current contract no longer guarantees, fix the expectation or version mapping. Do not conceal the mismatch with a generic “done” message.

Turn validation failures into specific corrections

Suppose the assistant submits a caption-generation request with six variants and an extra field named platform_url. The useful correction is to select an allowed variant count and remove the unsupported property after confirming the intended task. It is not to reinstall the client or request publication permissions.

A good error report identifies the failing field and expected constraint without including private content unnecessarily. A good retry changes only the invalid arguments while preserving the service's rules for action identity. If a mutation's arguments change, follow the documented idempotency behavior rather than reusing a key incorrectly.

Keep a few controlled examples in the integration notes: a valid minimal request, an invalid enum, a missing required field, and an unsupported property. These examples should contain placeholders or test objects, never live credentials or unrelated customer data.

The goal is not to make editors write JSON. It is to ensure that the client constructing requests can explain failures and recover without expanding scope or creating duplicate work.

Keep schema checks connected to human review

A schema can validate the structure of a caption but cannot prove that a product claim is accurate. It can enforce an array length but cannot prove that the chosen images tell a useful story. It can describe an approval URL but cannot decide whether the proposed post should go live.

Use schema validation as the first technical filter. Follow it with ownership checks, business rules, and the editorial review appropriate to the task. A technically valid request is ready for processing, not automatically ready for public publication.

After a tool update, compare the fields your workflow actually uses with the new reference and repeat a harmless test. That small maintenance habit prevents old examples from becoming persistent integration errors. Precise contracts make the connection predictable; thoughtful review makes its output worth using.

A useful review exercise is to compare the minimum valid request with the full request your client constructs. For every additional field, explain which user requirement it represents. Remove fields added merely because they appeared in an unrelated example, provided the current contract allows omission. This reduces accidental defaults and makes later failures easier to understand. The exercise also reveals when a conversational request contains a decision the user has not actually made, such as a destination or publication state. Resolve that decision before constructing the next operation instead of encoding a guess into a valid-looking payload.