Add support for exposing a subset of input schema attributes, with the option to fetch all attributes when needed

[jirispilka]

The Apify input schema is generally quite large and contains many attributes.
However, in practice, users only work with a small subset—usually just the required attributes or those needed for their specific use case.

One possible solution is to use smart tool descriptions.
Is it possible to leverage or adapt [elicitation](https://modelcontextprotocol.io/specification/draft/client/elicitation) for this?

This issue is open for discussion—let’s agree on the best approach before moving forward with implementation.

• Discuss and decide on the best way to implement this functionality
• Implement the agreed solution

[jirispilka]

Notes from Honza:

Do we have two levels of details (basic vs. full) ?

Let’s try it as follows:

• For list change supporting clients: On add-actor, only add simplified input schema and basic description to tools. Add info to prompt that on error, the client should call get-actor-details to fetch the full info of the Actor, including README. When get-actor-details is called, the actor tool schema is extended by the additional input fields
• For list change not-supporting clients: Same as above, but only add it to response text for LLM to process, i.e. no hard schema check
• Create unit tests for the input schema => json schema (simplified vs. full) transformation, use top 30 Actors’ input schema and check them vs. expected transformation output

[jirispilka]

From Honza:

Create unit tests for the input schema => json schema (simplified vs. full) transformation, use top 30 Actors’ input schema and check them vs. expected transformation output

[MQ37]

For list change supporting clients: On add-actor, only add simplified input schema and basic description to tools. Add info to prompt that on error, the client should call get-actor-details to fetch the full info of the Actor, including README. When get-actor-details is called, the actor tool schema is extended by the additional input fields

Sometimes it happens that the LLM calls the get-actor-details automatically after adding the Actor, this would break the workflow. I would personally create a separate tool actor-expose-whole-input (or something like that) that LLM would explicitly call when wanting to use advanced/all input parameters.

For list change not-supporting clients: Same as above, but only add it to response text for LLM to process, i.e. no hard schema check

If I get this correctly the tool would have the simplified input schema but we would tell LLM that there are additional parameters that it can pass? If so that this would not work, it worked in VSCode, but after an update they are validating input locally against the tool input schema so you cannot pass any additional parameters.

---

Maybe we could leverage the preview call-actor function that allows you to pass any parameter you want since it does not have any schema defined, it is generic, but we would have to refine and test the tool description so LLM actually never uses the tool unless it wants to pass parameters outside the default input schema of the Actor tools.

[MichalKalita]

The simplest solution is to define important parameters for the 30 most-used Actors and ignore the unimportant parameters.
All that is required is important, and some optional items can be too. Arguments can be validated against the full schema.

[MQ37]

Arguments can be validated against the full schema

The MCP client can validate that locally (Claude desktop and VSCode) actually does that and in order for any additional parameter to pass we would have to send whole input schema to the MCP client and thus the LLM so all of this would not make sense.

[MichalKalita]

Arguments can be validated against the full schema

The MCP client can validate that locally (Claude desktop and VSCode) actually does that and in order for any additional parameter to pass we would have to send whole input schema to the MCP client and thus the LLM so all of this would not make sense.

I am afraid the client sends the schema to LLM, and we don't want to do it. We can hide only the really not used parameters, but that's probably the biggest issue.

I'm just looking at Google Maps Scraper. It has an incredible number of optimal parameters. I think most LLM will use only the first two: location and limit.

I think we have only one option for finding the right way: find data about Actors' usage and analyze the usage of optional parameters for each.

[MQ37]

I am afraid the client sends the schema to LLM, and we don't want to do it.

I agree the we would like to somehow limit the input schema but in order for LLM to use it it has to somehow "read" the input schema, there is no way around that.

I think the best solution would be to create a specific version if input schema for LLMs where developer would include only crucial and simplified version if the input schema.

[jirispilka]

I think we need to discuss this in person (because we can :)). It will be faster and more efficient.

[MichalKalita]

I partially agree with a specific LLM schema.
It will be much faster and easier to hardcode for the top 30 Agents. We can have it this week.

It has 2 questions:

1. Is it possible to call Actor with the full input schema?
   I think no. MCP is not a REST API and should not be an alias for it.

2. Who is responsible for a good input schema for LLMs? Actor authors / Apify as a service provider
   I have no idea.

@jirispilka, we need a resolution here

[jirispilka]

Note:

• input schema has basic params and advanced (collapsed in sectionCaption)
• expose basic parameter,s with all params in description,
• in the schema - add atribute any that will take any parameters

[MQ37]

By default, zodToJsonSchema adds additionalProperties: false to the tool's inputSchema, but only for internal tools; Actor tools do not have this property set. And based on the documentation, it appears that additional properties are allowed by default:

By default any additional properties are allowed.
https://json-schema.org/understanding-json-schema/reference/object#additionalproperties

So this property will most probably not help us achieve this, and we should use the approach we discussed.

[jirispilka]

Add also ability to expose all attributes using a query parameter ?