run_actor

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It does disclose useful traits: the run can be waited on ('How long to wait for the run to finish', default 180s), memory can be overridden, and total count is always returned. However it omits what happens on timeout, whether the run is billed/quota-limited, and any auth requirement, which matters for an externally-executed job.

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 one-line purpose leads, followed by a compact per-argument block. Every entry is substantive and front-loaded; only the restatement of defaults that also live in the schema is slightly redundant.

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?

An output schema exists, so return-shape explanation is rightly omitted, and all parameters are covered. For a networked, long-running execution tool the description stops short of error/timeout behavior and any auth or rate/quota caveats, leaving that gap.

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 0%, so the description must compensate, and it largely does: it documents all five parameters with meaning, example format for actor ('gleif-lei-lookup' or 'tinyrex/<name>'), the input-object convention ('same fields as on the Apify Store'), and the semantics of max_items (50 default, total count always included). Minor gap: memory_mbytes lacks units/guidance beyond 'Apify default if omitted'.

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 ('Run a TinyRex Apify actor') plus the return ('return dataset items'), which distinguishes it from the sibling list_actors. It references list_actors explicitly as a source for input examples, giving partial sibling differentiation, but never says plainly 'use list_actors to discover actors, use this to execute one'.

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 gives one concrete routing hint ('Use list_actors exampleInput as a starting point'), which implies a read-then-run workflow, but there is no explicit when-to-use/when-not guidance, no mention of prerequisites (Apify token/auth) or cost implications of launching a run.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.