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

Annotations already declare readOnlyHint=false and destructiveHint=true, but the description adds substantial context beyond them: the run is queued, executes as a script on its own machine, consumes compute, inherits organisation and project Secrets as environment variables, and returns immediately with an _id and queued status. It also documents failure modes ('Unknown entrypointId', 'Project not found'). It could have said more about cost or concurrency limits on the destructive compute consumption, which keeps it from a 5.

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 core action and its async contract before branching into entrypoint and sibling guidance. Dense and information-rich, but the middle entrypoint discussion is a long run-on chain of clauses that could be tightened without losing content.

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 fire-and-forget async mutation with no output schema, the description covers the return shape (run id plus queued status), the follow-up tools for polling and logs, entrypoint resolution, permissions, and error cases. Nothing an agent needs to invoke it 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%, so baseline is 3; the description earns above that by explaining entrypointId's default ('main'), which project types start with entrypoints and which start with none, and what happens when the id is unknown. projectId and pythonProjectId are left to the schema, which already documents their sources.

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 ('Start one run of a Python project's entrypoint now') and immediately contrasts with the sibling scheduling tool. An agent can distinguish it from fastero_run_notebook, fastero_set_python_schedule, and fastero_list_python_runs 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?

Explicitly names the alternatives and the condition that selects each: fastero_list_python_runs for status, fastero_get_python_run_log for output, fastero_set_python_schedule for timetables, fastero_ensure_python_entrypoint when an entrypoint is missing. It also states the permission prerequisite ('Owners, admins and editors').

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