martin_run

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

Annotations already signal destructiveHint=true and idempotentHint=false, so the safety profile is partially covered. The description adds key behavioral detail beyond the annotations: the tool hard-blocks until prerequisite receipts exist, and it returns spend and verification state. It does not elaborate on repo-modifying side effects or cost controls, but the destructive annotation plus the explicit execution stance makes the most critical behavior clear.

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 description is two tight sentences. The first sentence delivers the action and outputs; the second anchors the critical precondition. There is no filler, and the most decision-relevant information is front-loaded.

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 fourteen-parameter execution tool with partial annotations and an output schema, the description covers the key decision factors: what it does, what it returns, and the prerequisite receipts. The blocking behavior could have been padded with explicit guidance about cost/budget side effects, but those are already captured by schema parameter descriptions like maxUsd, maxTokens, and maxIterations. Slight polish would be a direct sentence saying this is the call that actually mutates the repository, but the overall context is solid.

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 100%, and every parameter already has a meaningful description in the schema, including objective, engine, and budgets. The tool description itself adds no parameter-level semantics, which is acceptable because the schema already carries the full load. Baseline 3 is appropriate here since complexity is present but no gap exists for the description to fill.

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?

The description clearly states the specific action—executing a governed Martin Loop run on a coding task—and names the returned data: run summary, spend, artifact rollup, and verification state. This is enough to distinguish it from sibling tools like martin_get_run, martin_status, and martin_eval, which are not execution tools.

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 states when a caller should not proceed: the run hard-blocks unless martin_doctor, martin_estimate, martin_plan, and martin_preflight receipts already exist. That provides practical preconditions and tells the agent to prepare those steps first. It doesn't explicitly contrast with martin_continue or martin_cancel, but the hard-block and receipt language gives strong usage direction.

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